Apollo inside of NuxtJS

• Nuxt.js module to use vue-apollo
• uses internally same approach as vue-cli-plugin-apollo

Warning

This version requires Vue 2.6+ with serverPrefetch support. For example:

1npm install --save vue@2.6.6 vue-template-compiler@2.6.6 vue-server-renderer@2.6.6

Sometime you may need to remove/rebuild package-lock.json/yarn.lock to make it work.

Setup

1- Install apollo module

1npm install --save @nuxtjs/apollo

or

1yarn add @nuxtjs/apollo

2- Load @nuxtjs/apollo module

1// nuxt.config.js
2
3export default {
4  modules: [
5    '@nuxtjs/apollo',
6  ],
7
8  apollo: {
9    clientConfigs: {
10      default: {
11        httpEndpoint: 'http://localhost:4000',
12      }
13    }
14  }
15}

3- Loading *.gql or *.graphql files (optional)

Install graphql-tag

1npm install --save graphql-tag

or

1yarn add graphql-tag

:warning: Typescript users

Add a gql.d.ts file in your sources folder with the following content:

1declare module '*.gql' {
2  import { DocumentNode } from 'graphql'
3
4  const content: DocumentNode
5  export default content
6}
7
8declare module '*.graphql' {
9  import { DocumentNode } from 'graphql'
10
11  const content: DocumentNode
12  export default content
13}

Usage

You have a successfully enabled vue-apollo in your project.

Checkout Official example and vue-apollo official documentation for how to use vue-apollo inside your application

Advanced configuration

1{
2  // Add apollo module
3  modules: ['@nuxtjs/apollo'],
4
5  apollo: {
6    // Sets up the apollo client endpoints
7    clientConfigs: {
8      // recommended: use a file to declare the client configuration (see below for example)
9      default: '~/plugins/my-alternative-apollo-config.js',
10
11      // you can setup multiple clients with arbitrary names
12      alternativeClient: {
13        // required
14        httpEndpoint: 'http://localhost:4000',
15
16        // override HTTP endpoint in browser only
17        browserHttpEndpoint: '/graphql',
18
19        // See https://www.apollographql.com/docs/link/links/http.html#options
20        httpLinkOptions: {
21          credentials: 'same-origin'
22        },
23
24        // You can use `wss` for secure connection (recommended in production)
25        // Use `null` to disable subscriptions
26        wsEndpoint: 'ws://localhost:4000',
27
28        // LocalStorage token
29        tokenName: 'apollo-token',
30
31        // Enable Automatic Query persisting with Apollo Engine
32        persisting: false,
33
34        // Use websockets for everything (no HTTP)
35        // You need to pass a `wsEndpoint` for this to work
36        websocketsOnly: false
37      },
38    },
39    
40    /**
41     * default 'apollo' definition
42     */
43    defaultOptions: {
44      // See 'apollo' definition
45      // For example: default query options
46      $query: {
47        loadingKey: 'loading',
48        fetchPolicy: 'cache-and-network',
49      },
50    },
51    
52    // setup a global query loader observer (see below for example)
53    watchLoading: '~/plugins/apollo-watch-loading-handler.js',
54    
55    // setup a global error handler (see below for example)
56    errorHandler: '~/plugins/apollo-error-handler.js',
57
58    // Sets the authentication type for any authorized request.
59    authenticationType: 'Bearer', 
60
61    // Token name for the cookie which will be set in case of authentication
62    tokenName: 'apollo-token',
63
64    // [deprecated] Enable the graphql-tag/loader to parse *.gql/*.graphql files
65    includeNodeModules: true,
66
67    // Cookie parameters used to store authentication token
68    cookieAttributes: {
69      /**
70        * Define when the cookie will be removed. Value can be a Number
71        * which will be interpreted as days from time of creation or a
72        * Date instance. If omitted, the cookie becomes a session cookie.
73        */
74      expires: 7,
75
76      /**
77        * Define the path where the cookie is available. Defaults to '/'
78        */
79      path: '/',
80
81      /**
82        * Define the domain where the cookie is available. Defaults to
83        * the domain of the page where the cookie was created.
84        */
85      domain: 'example.com',
86
87      /**
88        * A Boolean indicating if the cookie transmission requires a
89        * secure protocol (https). Defaults to false.
90        */
91      secure: false,
92    },
93  }
94}
95

Apollo clientOptions using file configuration

:warning: In case you need to declare functions (like getAuth or inMemoryCacheOptions.fragmentMatcher) inside apollo configuration, you MUST define your clientOptions using an external file

1// ~/plugins/my-alternative-apollo-config.js
2
3export default (context) => {
4  return {
5    httpEndpoint: 'http://localhost:4000/graphql-alt',
6
7    /*
8     * For permanent authentication provide `getAuth` function.
9     * The string returned will be used in all requests as authorization header
10     */
11    getAuth: () => 'Bearer my-static-token',
12  }
13}

watchLoading example

1// ~/plugins/apollo-watch-loading-handler.js
2
3export default (isLoading, countModifier, nuxtContext) => {
4  loading += countModifier
5  console.log('Global loading', loading, countModifier)
6}
7

errorHandler example

1// ~/plugins/apollo-error-handler.js
2
3export default ({ graphQLErrors, networkError, operation, forward }, nuxtContext) => {
4  console.log('Global error handler')
5  console.log(graphQLErrors, networkError, operation, forward)
6}
7

Options

You can either (in a simple setup) just add an object as described above. If you need to overwrite cache or the default getAuth() function then use a path to your config file which returns the client config options.

clientConfigs Option: required

Sets up the apollo client endpoints. All available options for each endpoint you find here

Check out official vue-apollo-cli where possible usecases are presented.

clientConfigs.default Object: required

clientConfigs. Object|Path: optional

tokenName String: optional, default: 'apollo-token'

Token name for the cookie which will be set in case of authentication. You can also provide an option tokenName in each of your clientConfigs to overwrite the default. When each request is made, the value of whatever is in this cooke will be sent in an "Authorization" HTTP header as specified by authenticationType below.

authenticationType String: optional, default: 'Bearer'

Sets the authentication type for any authorized request. Modify this if the authentication type your GraphQL API requires is not the default Bearer. All requests will then be sent with the appropriate HTTP header in the format: "Authorization: " (Eg. Authorization: Bearer abc123).

If your backend requires an Authorization header in the format "Authorization: ", without any prefix, then you should set this value to an empty string.

includeNodeModules Boolean: optional, default: false

In case you use *.gql files inside of node_module folder you can enable the graphql-tag/loader to parse the files for you.

Authentication

You have following methods for authentication available:

1 // set your graphql-token
2 this.$apolloHelpers.onLogin(token /* if not default you can pass in client as second argument, you can set custom cookies attributes object as the third argument, and you can skip reset store as the fourth argument */)
3 // unset your graphql-token
4 this.$apolloHelpers.onLogout(/* if not default you can pass in client as first argument, and you can skip reset store as the second argument */)
5 // get your current token (we persist token in a cookie)
6 this.$apolloHelpers.getToken(/* you can provide named tokenName if not 'apollo-token' */)

Check out the full example

User login

1// ~/components/my-component.js
2
3export default {
4  methods: {
5    async onSubmit () {
6      const credentials = this.credentials
7      try {
8          const res = await this.$apollo.mutate({
9              mutation: authenticateUserGql,
10              variables: credentials
11          }).then(({data}) => data && data.authenticateUser)
12          await this.$apolloHelpers.onLogin(res.token)
13      } catch (e) {
14          console.error(e)
15      }
16    },
17  }
18}

User logout

1// ~/components/my-component.js
2
3export default {
4  methods: {
5    async onLogout () {
6      await this.$apolloHelpers.onLogout()
7    },
8  }
9}

getToken

1// ~/middleware/isAuth.js
2
3export default ({app, error}) => {
4  const hasToken = !!app.$apolloHelpers.getToken()
5  if (!hasToken) {
6    error({
7      errorCode:503, 
8      message:'You are not allowed to see this'
9    })
10  }
11}

Examples to access the defaultClient of your apolloProvider

Vuex actions

1// ~/store/my-store.js
2
3export default {
4  actions: {
5    foo (store, payload) {
6      let client = this.app.apolloProvider.defaultClient
7    }
8  }
9}

asyncData/fetch method of page component

1// ~/components/my-component.js
2
3export default {
4  asyncData (context) {
5    let client = context.app.apolloProvider.defaultClient
6  }
7}

nuxtServerInit

1export default {
2  nuxtServerInit (store, context) {
3    let client = context.app.apolloProvider.defaultClient
4  }
5}

access client or call mutations and queries of any method inside of component

1// ~/components/my-component.js
2
3export default {
4  methods: {
5    foo () {
6      // receive the associated Apollo client 
7      const client = this.$apollo.getClient()
8
9      // most likely you would call mutations like following:
10      this.$apollo.mutate({mutation, variables})
11      
12      // but you could also call queries like this:
13      this.$apollo.query({query, variables})
14        .then(({ data }) => {
15          // do what you want with data
16        })
17    }
18  }
19}

Once you get the client, you can access its methods and properties. See API Reference

Smart queries on any component

1// nuxt.config.js
2
3export default {
4  apollo: {
5    foo: {
6      query: fooGql,
7      variables () {
8        return {
9          myVar: this.myVar
10        }
11      }
12    }
13  }
14}

See vue-apollo documentation for more information on smart queries

Add GQL file recognition on node_modules

1// nuxt.config.js
2
3export default {
4  apollo: {
5    clientConfigs: {
6      default: '~/apollo/client-configs/default.js'
7    },
8    includeNodeModules: true
9  }
10}

Upgrade

Upgrade Guide apollo-module v3 => v4

Version 4 of this module leaves you with zero configuration. This means we use the best possible approach available from vue-cli-plugin-apollo and the same configuration behaviour. This means you don't need to wire up your own configuration, simply pass

Edit your configuration as following:

1// nuxt.config.js
2
3export default {
4  apollo: {
5    clientConfigs: {
6      default:{
7        httpEndpoint: YOUR_ENDPOINT,
8        wsEndpoint: YOUR_WS_ENDPOINT
9      }
10    }
11  }
12}
13

Upgrade Guide apollo-client v1 => v2

Version 3 of this module is using apollo-client 2.x. You need to make sure to update all your middle/afterware according to the upgrade guide of apollo-client. Check this source for a reference: https://www.apollographql.com/docs/apollo-server/migration-two-dot/

Troubleshooting

Proxies

CORS errors are most often resolved with proxies. If you see a Cross-Origin-Request error in your client side console look into setting up a proxy. Check out https://github.com/nuxt-community/proxy-module for quick and straight forward setup.

ctx.req.session - req is undefined

This is just a placeholder. You'll want to replace it with whatever storage mechanism you choose to store your token. Here is an example using local storage : https://github.com/Akryum/vue-apollo/issues/144

Contribute and wire up setup

Setup the required fields in .env file in root folder

1# cat .env
2HTTP_ENDPOINT=https://your-endpoint
3WS_ENDPOINT=wss://your-endpoint

In index.vue the login process requires that the gql endpoint enables a mutation which returns a valid token:

1mutation authenticateUser($email:String!,$password:String!){
2    authenticateUser(email: $email, password: $password) {
3        token
4        id
5    }
6}

If your gql backend is prepared start running nuxt as follow

1npm install
2npm run dev