Authentication

Configure Nuxt Apollo via the apollo property.

Token Storage

There are two (2) token storage modes supported by Nuxt Apollo, These include localStorage and cookie, with the latter being the default and recommended option.

tokenStorage is set to cookie by default. This can be changed to localStorage by modifying the tokenStorage property in the apollo section of nuxt config, or on a per client basis.

Nuxt Apollo's authentication helper functions work closely with the token storage mode, and ultimately determines where the token is stored and retrieved from when these functions are triggered.

Local Storage

The localStorage mode can be enabled by setting the tokenStorage property to localStorage. This can be applied globally to all Apollo clients by passing the tokenStorage property to the apollo section in your nuxt config, or per client.

nuxt.config.ts
export default defineNuxtConfig({  modules: ['@nuxtjs/apollo'],  apollo: {    clients: {      default: {        tokenStorage: 'localStorage',      }    }  }})
Doesn't support server-side rendering (SSR).

Due to localStorage being a browser-only feature, it is not possible to use this mode for server-side rendering (SSR).

Cookie storage is the recommended approach and is also required for server-side rendering (SSR).

This module provides a proxyCookies option (enabled by default) which when enabled, will proxy all cookies from the client to the server. This is particularly useful for server-side rendering (SSR).

credentials

Request credentials determine whether or not the browser should send cookies to the server.

Options:

  • same-origin (default): Instruct the browser to send cookies to the server if the request is made from the same domain.
  • include: Required if the backend server lives on a different domain that the client. Instructs the browser to send cookies to 3rd party domains.
nuxt.config.ts
export default defineNuxtConfig({  modules: ['@nuxtjs/apollo'],  apollo: {    clients: {      default: {        httpLinkOptions: {          credentials: 'include'        }      }    }  }})
The backend server must be configured to allows credentials from the desired origins.

httpOnly

Nuxt Apollo is designed to support the httpOnly cookie option with minimal effort on your part. This option prevents cookies from being accessed by JavaScript, hence it renders the authentication helpers trivial.

Auth Hook

Nuxt Apollo provides a SSR friendly auth token retrieval logic which meet the needs of most applications. This is based on the configured client's tokenStorage.

The apollo:auth hook allows you to override the aforementioned behavior of Nuxt Apollo, and provide custom logic for manually retrieving and applying the authentication token accordingly. This should account for client and server modes.

When the apollo:auth hook is implemented, The getToken auth helper adheres to the custom logic provided to the hook.
plugins/apollo.ts
export default defineNuxtPlugin((nuxtApp) => {  // access cookie for auth  const cookie = useCookie('<cookie_name>')  nuxtApp.hook('apollo:auth', ({ client, token }) => {    // `client` can be used to differentiate logic on a per client basis.    // apply apollo client token    token.value = '<secret_token>'  })})
Nuxt composables such as useState, useCookie, useRequestHeaders and more, should not be called directly in the apollo:auth hook. This would result in a nuxt instance unavailable error on the server-side.
Table of Contents