# GraphQL integration for Nuxt

::u-page-hero
#title
Nuxt [Apollo]{style="color: var(--color-primary-500)"}

#description
Leverage [Vue Apollo](https://v4.apollo.vuejs.org){rel="nofollow"} to effortlessly integrate GraphQL into your Nuxt 3 projects.

#links
  :::u-button
  ---
  color: neutral
  size: xl
  to: https://apollo.nuxtjs.org/getting-started/quick-start
  trailing-icon: i-lucide-arrow-right
  ---
  Get started
  :::

  :::copy-code-input{source="npx nuxi@latest module add graphql"}
  :::

  :::u-page-section
  #title
  Everything you need for GraphQL in Nuxt
  
  #features
    ::::u-page-feature
    #title
    SSR Support
    
    #description
    Fully supports server-side rendering, giving you full control over where your GraphQL queries are executed.
    ::::
  
    ::::u-page-feature
    #title
    Minimal Configuration
    
    #description
    Configure your Apollo Client with just a few lines of code, making it easy to get started.
    ::::
  
    ::::u-page-feature
    #title
    Vue-Apollo Composables
    
    #description
    Use Vue Apollo's powerful composables to manage your GraphQL queries and mutations seamlessly.
    ::::
  
    ::::u-page-feature
    #title
    HMR for external Apollo Client configuration
    
    #description
    Enjoy hot module replacement for your Apollo Client configuration, allowing you to make changes without restarting your server.
    ::::
  :::
::


# Quick Start

Integrate Nuxt Apollo into your project.

---

## Installation

1. Add the `@nuxtjs/apollo` development dependency. :code-group[```bash \[Yarn\]
   yarn add -D @nuxtjs/apollo@next
   ``````bash \[NPM\]
   npm i -D @nuxtjs/apollo@next
   ``````bash \[pnpm\]
   pnpm add @nuxtjs/apollo@next --save-dev
   ```]
2. Enable the module.
   ```ts [nuxt.config.ts]
   import { defineNuxtConfig } from 'nuxt/config'

   export default defineNuxtConfig({
     modules: ['@nuxtjs/apollo'],
   })
   ```
3. Add Nuxt Apollo Configuration.
   ```ts [nuxt.config.ts]
   import { defineNuxtConfig } from 'nuxt/config'

   export default defineNuxtConfig({
     modules: ['@nuxtjs/apollo'],

     apollo: {
       clients: {
         default: {
           httpEndpoint: 'https://spacex-production.up.railway.app'
         }
       },
     },
   })
   ```
4. Example Usage. :alert[Nuxt Apollo automatically imports the `gql` tag function as well as [key composables](https://apollo.nuxtjs.org/getting-started/composables).]
   ```vue [app.vue]
   <template>
     <p>There are {{ data?.ships?.length || 0 }} ships.</p>
   </template>

   <script lang="ts" setup>
   const query = gql`
     query getShips($limit: Int!) {
       ships(limit: $limit) {
         id
         name
       }
     }
   `
   const variables = { limit: 5 }

   const { data } = await useAsyncQuery(query, variables)
   </script>
   ```


# Configuration

Configure Nuxt Apollo via the `apollo` property.

---

## Defaults

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/apollo'],

  apollo: {
    autoImports: true,
    authType: 'Bearer',
    authHeader: 'Authorization',
    tokenStorage: 'cookie',
    proxyCookies: true,
    clients: {}
  }
})
```

## `autoImports`

- Default: `true`

Determine if vue-apollo composables should be automatically imported and accessible within your nuxt app.

## `authType`

- Default: `Bearer`

Specify the Authentication scheme.

## `authHeader`

- Default: `Authorization`

Name of the Authentication token header.

## `tokenStorage`

- Default: `cookie`

Specify if the auth token should be stored in `cookie` or `localStorage`. `Cookie` storage is required for SSR.

## `proxyCookies`

- Default: `true`

Specify if client cookies should be proxied to the server.

## `clients`

Configure your Apollo Client instances.

::code-group
```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/apollo'],

  apollo: {
    clients: {
      default: {
        httpEndpoint: '',
        browserHttpEndpoint: '',
        wsEndpoint: '',
        httpLinkOptions: {},
        wsLinkOptions: {},
        wsEndpoint: '',
        websocketsOnly: false,
        connectToDevTools: false,
        defaultOptions: {},
        inMemoryCacheOptions: {},
        tokenName: 'apollo:<client-name>.token',
        tokenStorage: 'cookie',
        authType: 'Bearer',
        authHeader: 'Authorization'
      },
      other: './apollo/other.ts'
    }
  }
})
```

```ts [apollo/other.ts]
import { defineApolloClient } from '@nuxtjs/apollo/config'

export default defineApolloClient({
  httpEndpoint: '',
  browserHttpEndpoint: '',
  wsEndpoint: '',
  httpLinkOptions: {},
  wsLinkOptions: {},
  wsEndpoint: '',
  websocketsOnly: false,
  connectToDevTools: false,
  defaultOptions: {},
  inMemoryCacheOptions: {},
  tokenName: 'apollo:<client-name>.token',
  tokenStorage: 'cookie',
  authType: 'Bearer',
  authHeader: 'Authorization'
})
```
::

- ### `httpEndpoint`

The GraphQL endpoint.

- ### `browserHttpEndpoint`

Provide a GraphQL endpoint to be used client-side. Overrides `httpEndpoint`.

- ### `httpLinkOptions`

Provide additional configuration for the [HttpLink](https://www.apollographql.com/docs/link/links/http.html#options){rel="nofollow"}.

- ### `wsLinkOptions`

Provide additional configuration for the [`GraphQLWsLink`](https://github.com/enisdenjo/graphql-ws/blob/master/docs/interfaces/client.ClientOptions.md){rel="nofollow"}.

- ### `wsEndpoint`

Specify a websocket endpoint to be used for subscriptions. The `wss` protocol is recommended in production.

- ### `websocketsOnly`

Specify if the client should solely use WebSocket. requires [`wsEndpoint`](https://apollo.nuxtjs.org/#wsendpoint).

- ### `connectToDevTools`
  - Default: `true`

Specify if the client should be able to connect to the Apollo Client Devtools in production mode.

- ### `defaultOptions`

Configure default options to be applied to the apollo client.

- ### `inMemoryCacheOptions`

Additional configuration for the in-memory cache.

- ### `tokenName`
  - Default: `apollo:<client-name>.token"`

Specify the name under which the token will be stored.

- ### `tokenStorage`
  - Default: `cookie`

Specify if the auth token should be stored in `cookie` or `localStorage`. `Cookie` storage is required for SSR.

- ### `authType`
  - Default: `Bearer`

Specify the Authentication scheme.

- ### `authHeader`
  - Default: `Authorization`

Name of the Authentication token header.


# Composables

Nuxt Apollo provides and [Auto Imports](https://v3.nuxtjs.org/guide/concepts/auto-imports){rel="nofollow"} key composables for seamless usage throughout your application.

---

## useApollo

`useApollo` allows you to utilize [Nuxt Apollo's authentication helpers](https://apollo.nuxtjs.org/getting-started/auth-helpers) as well as easily access the configured Apollo clients.

```ts
const { clients, getToken, onLogin, onLogout } = useApollo()
```

## useAsyncQuery

This is a convenience wrapper around Nuxt's [useAsyncData](https://v3.nuxtjs.org/api/composables/use-async-data/){rel="nofollow"} that allows you to easily query the Apollo client. The returned result is the extracted data property from the GraphQL query.

`useAsyncQuery` is primarily used for querying data when a page or component is initially loaded. Have a look at [`useQuery`](https://apollo.nuxtjs.org/#usequery) for fetching data upon user interaction.

```ts
const query = gql`
query getShips($limit: Int!) {
  ships(limit: $limit) {
    id
  }
}`

const { data } = await useAsyncQuery(query, { limit: 2 })

if (data.value?.ships) {
  // log response
  console.log(data.value.ships)
}
```

## useLazyAsyncQuery

The `useLazyAsyncQuery` composable provides a wrapper around [`useAsyncQuery`](https://apollo.nuxtjs.org/#useasyncquery) that lazily loads the specified query.

Unlike it's counterpart [`useAsyncQuery`](https://apollo.nuxtjs.org/#useasyncquery), `useLazyAsyncQuery` is non-blocking, hence the `null` state of your result must be manually handled.

```ts
const query = gql`
  query currentUser { 
    whoAmI { 
      id 
    }
  }
`

const { data } = await useLazyAsyncQuery(query)
```

## useQuery

This is the primary method of querying your GraphQL server, unlike [`useAsyncQuery`](https://apollo.nuxtjs.org/#useasyncquery) which is best used for initially fetching data in SSR applications, `useQuery` can comfortably be used in any scenario.

```ts
const query = gql`
  query getShips($limit: Int!) {
    ships(limit: $limit) {
      id
    }
  }
`

const variables = { limit: 5 }

const { result } = useQuery(query, variables)
```

> More Information on [Vue Apollo's `useQuery`](https://v4.apollo.vuejs.org/api/use-query.html#usequery){rel="nofollow"}

## useMutation

The `useMutation` composable allows you to modify server-side data

```ts
const query = gql`
  mutation addUser ($input: UserInput!) {
    addUser (input: $input) {
      id
    }
  }
`

const variables = {
  name: 'John Doe',
  email: 'jd@example.com'
}

const { mutate } = useMutation(query, { variables })
```

> More Information on [Vue Apollo's `useMutation`](https://v4.apollo.vuejs.org/api/use-mutation.html#usemutation){rel="nofollow"}

## useSubscription

The `useSubscription` composable allows you to interface with WebSocket compliant GraphQL servers to listen for realtime updates.

::alert
Nuxt Apollo currently only supports subscriptions over WebSockets.
::

```ts
const query = gql`
  subscription onMessageAdded($channelId: ID!) {
    messageAdded(channelId: $channelId) {
      id
      text
    }
  }
`

const variables = { channelId: 'abc' }

const { result } = useSubscription(query, variables)
```

> More Information on [Vue Apollo's `useSubscription`](https://v4.apollo.vuejs.org/api/use-subscription.html#usesubscription){rel="nofollow"}


# Auth Helpers

Helper functions for working with authentication in Apollo.

---

Nuxt Apollo provides three (3) auth helpers which can be easily plugged into your authentication flow to interface with configured Apollo clients.

## `getToken`

Retrieve the auth token token for the specified client.

This adheres to the [`apollo:auth` hook](https://apollo.nuxtjs.org/recipes/authentication#auth-hook). and will attempt to automatically retrieve the token from the `apollo:auth` hook.

```ts
const { getToken } = useApollo()

const token = getToken()

const otherToken = getToken('<client_name>')
```

### `getToken` Reference

- `client`: The Apollo client who's token should be retrieved.

## `onLogin`

Used to apply the given auth token to the specified Apollo client. This is required if your GraphQL API expects authentication to be passed via a HTTP header.

By default, this function will reset the Apollo client cache and re-execute all queries, this behavior can be averted by passing `false` as the third parameter (`skipResetStore`).

```ts
const { onLogin } = useApollo()

function handleLogin() {
  // your login flow...

  onLogin(token)
}
```

### `onLogin` Reference

- `token`: The token to be applied.
- `client`: The Apollo client to authenticate.
  - Default: `default`
- `skipResetStore`: Whether to skip resetting the Apollo client cache.
  - Default: `false`

## `onLogout`

Used to remove the auth token from the specified Apollo client.

```ts
const { onLogout } = useApollo()

function handleLogout() {
  // your logout flow...

  onLogout()
}
```

### `onLogout` Reference

- `client`: The Apollo client to de-authenticate.
  - Default: `default`
- `skipResetStore`: Whether to skip resetting the Apollo client cache.
  - Default: `false`


# Authentication

Configure Nuxt Apollo via the `apollo` property.

---

## Token Storage

There are two (2) token storage modes supported by Nuxt Apollo, These include [`localStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage){rel="nofollow"} and [`cookie`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies){rel="nofollow"}, 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`](https://apollo.nuxtjs.org/getting-started/configuration#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.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/apollo'],

  apollo: {
    clients: {
      default: {
        tokenStorage: 'localStorage',
      }
    }
  }
})
```

::alert
Doesn't support server-side rendering (SSR).
::

Due to [`localStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage){rel="nofollow"} being a browser-only feature, it is not possible to use this mode for server-side rendering (SSR).

## Cookie Storage

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

This module provides a [`proxyCookies`](https://apollo.nuxtjs.org/getting-started/configuration#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](https://developer.mozilla.org/en-US/docs/Web/API/Request/credentials){rel="nofollow"} 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.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@nuxtjs/apollo'],

  apollo: {
    clients: {
      default: {
        httpLinkOptions: {
          credentials: 'include'
        }
      }
    }
  }
})
```

::alert
The backend server must be configured to allows credentials from the desired origins.
::

### `httpOnly`

Nuxt Apollo is designed to support the [`httpOnly`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#restrict_access_to_cookies){rel="nofollow"} 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`](https://apollo.nuxtjs.org/#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.

::alert
When the `apollo:auth` hook is implemented, The [getToken auth helper](https://apollo.nuxtjs.org/getting-started/auth-helpers#gettoken) adheres to the custom logic provided to the hook.
::

If you are looking to add your authentication token to your requests after your initial login mutation, you will need to set this plugin up (or a similar implementation)

Using a cookie:

```ts [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>'
  })
})
```

Using a pinia store:

```ts [plugins/apollo.ts]
import {useUserStore} from "~/store/user"

export default defineNuxtPlugin((nuxtApp) => {
  const userStore = useUserStore()
  nuxtApp.hook("apollo:auth", ({client, token}) => {
    if (userStore.authToken) { 
      token.value = userStore.authToken
    }
  })
})
```

Either of these will insert the appropriate authorization headers into your outgoing Apollo requests.

::alert{type="warning"}
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.
::


# Error Policy

Capture GraphQL errors and handle them accordingly.

---

## Error Hook

Nuxt Apollo provides a nuxt hook named `apollo:error` which captures errors encountered by apollo client(s).

```ts [plugins/apollo.ts]
export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.hook('apollo:error', (error) => {
    console.error(error)

    // Handle different error cases
  })
})
```


# TypesScript support

Nuxt Apollo gracefully support TypeScript.

---

## Type Casting

When using TypeScript, It's greatly beneficial to utilize the correct types of your data. This can be done by casting a custom type as demonstrated below.

```ts [app.vue]
const query = gql`
  query getShips($limit: Int!) {
    ships(limit: $limit) {
      id
      name
    }
  }
`

const variables = { limit: 5 }

type ShipsResult = {
  ships: {
    id?: string;
    name: string;
  }[]
}

useQuery<ShipsResult>(query, variables)
useAsyncQuery<ShipsResult>(query, variables)
```

## GraphQL documents

When importing `.gql` or `.graphql` files in TypeScript, A common error you may encounter is `"Cannot find module '*.gql' or its corresponding type declarations"`. This can be resolved by creating a type declaration file as seen below.

```ts [globals.d.ts]
declare module '*.gql' {
  import { DocumentNode } from 'graphql'
  const Schema: DocumentNode
  export = Schema
}

declare module '*.graphql' {
  import { DocumentNode } from 'graphql'
  const Schema: DocumentNode
  export = Schema
}
```