graphql.md 3.04 KB
Newer Older
Phil Hughes's avatar
Phil Hughes committed
1 2 3 4 5 6 7 8 9 10 11
# 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
Takuya Noguchi's avatar
Takuya Noguchi committed
12
[default client][default-client] that should be used. This setups the
Phil Hughes's avatar
Phil Hughes committed
13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29
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';
30
import createDefaultClient from '~/lib/graphql';
Phil Hughes's avatar
Phil Hughes committed
31 32 33
Vue.use(VueApollo);

const apolloProvider = new VueApollo({
34
  defaultClient: createDefaultClient(),
Phil Hughes's avatar
Phil Hughes committed
35 36 37 38 39 40 41 42 43 44 45
});

new Vue({
  ...,
  apolloProvider,
  ...
});
```

Read more about [Vue Apollo][vue-apollo] in the [Vue Apollo documentation][vue-apollo-docs].

46 47 48
### Local state with `apollo-link-state`

It is possible to use our Apollo setup with [apollo-link-state][apollo-link-state] by passing
49 50 51
in a resolvers object when creating the default client. The default state can be set by writing
to the cache after setting up the default client.

52 53 54 55 56 57 58

```javascript
import Vue from 'vue';
import VueApollo from 'vue-apollo';
import createDefaultClient from '~/lib/graphql';
Vue.use(VueApollo);

59 60 61 62 63 64 65 66 67 68 69 70 71 72 73
const defaultClient = createDefaultClient({
  Query: {
    ...
  },
  Mutations: {
    ...
  },
});

defaultClient.cache.writeData({
  data: {
    isLoading: true,
  },
});

74
const apolloProvider = new VueApollo({
75
  defaultClient,
76 77 78
});
```

Phil Hughes's avatar
Phil Hughes committed
79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116
### 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/
117
[apollo-link-state]: https://www.apollographql.com/docs/link/links/state.html