diff options
author | Phil Hughes <me@iamphill.com> | 2018-11-28 13:00:03 +0300 |
---|---|---|
committer | Phil Hughes <me@iamphill.com> | 2018-11-28 13:00:03 +0300 |
commit | 24b4c1e8bf5abf4b91a6a6bf1d154c3af70c5df7 (patch) | |
tree | f67480d8c8c4e9a669c179713580cee3e3aeb9b7 /doc/development/fe_guide/graphql.md | |
parent | 385e8f712cb5a8109c46eb33fd8fd5d8e1a4a6a2 (diff) |
Added frontend GraphQL docs
Diffstat (limited to 'doc/development/fe_guide/graphql.md')
-rw-r--r-- | doc/development/fe_guide/graphql.md | 83 |
1 files changed, 83 insertions, 0 deletions
diff --git a/doc/development/fe_guide/graphql.md b/doc/development/fe_guide/graphql.md new file mode 100644 index 00000000000..f55f01720fd --- /dev/null +++ b/doc/development/fe_guide/graphql.md @@ -0,0 +1,83 @@ +# GraphQL + +We use [Apollo] and [Vue Apollo][vue-apollo] for working with GraphQL +on the frontend. + +In order to use GraphQL, you need to enable the `graphql` feature flag, +read more about [Feature Flags][feature-flags]. + +## Apollo Client + +To save duplicated clients getting created in different apps, we have a +[default client][defualt-client] that should be used. This setups the +Apollo client with the correct URL and also sets the CSRF headers. + +## GraphQL Queries + +To save query compilation at runtime, webpack can directly import `.graphql` +files. This allows webpack to preprocess the query at compile time instead +of the client doing compilation of queries. + +## Usage in Vue + +To use Vue Apollo, import the [Vue Apollo][vue-apollo] plugin as well +as the default client. This should be created at the same point +the Vue application is mounted. + +```javascript +import Vue from 'vue'; +import VueApollo from 'vue-apollo'; +import defaultClient from '~/lib/graphql'; +Vue.use(VueApollo); + +const apolloProvider = new VueApollo({ + defaultClient, +}); + +new Vue({ + ..., + apolloProvider, + ... +}); +``` + +Read more about [Vue Apollo][vue-apollo] in the [Vue Apollo documentation][vue-apollo-docs]. + +### Testing + +With [Vue test utils][vue-test-utils] it is easy to quickly test components that +fetch GraphQL queries. The simplest way is to use `shallowMount` and then set +the data on the component + +```javascript +it('tests apollo component', () => { + const vm = shallowMount(App); + + vm.setData({ + ...mock data + }); +}); +``` + +## Usage outside of Vue + +It is also possible to use GraphQL outside of Vue by directly importing +and using the default client with queries. + +```javascript +import defaultClient from '~/lib/graphql'; +import query from './query.graphql'; + +defaultClient.query(query) + .then(result => console.log(result)); +``` + +Read more about the [Apollo] client in the [Apollo documentation][apollo-client-docs]. + +[Apollo]: https://www.apollographql.com/ +[vue-apollo]: https://github.com/Akryum/vue-apollo/ +[vue-apollo-docs]: https://akryum.github.io/vue-apollo/ +[feature-flags]: ../feature_flags.md +[default-client]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/javascripts/lib/graphql.js +[apollo-client-docs]: https://www.apollographql.com/docs/tutorial/client.html +[vue-test-utils]: https://vue-test-utils.vuejs.org/ |