Nuxt Apollo Client Module

A Nuxt module for integrating Apollo Client with SSR, Codegen and Offline support.

Features

• Apollo Client integration with Nuxt 3
• Server-Side Rendering (SSR) support
• GraphQL Code Generator integration
• Offline support (mutations)
• Multiple client support
• File Upload support
• Automatic token management
• Automatic type generation for queries and mutations
• Auto-imports for generated composables and types
• Production-ready 📦

Installation

1npm install nuxt-apollo-client
2# or
3yarn add nuxt-apollo-client

Everything is set up for you: 🚀

• No need to install Apollo Client or GraphQL codegen packages
• All necessary dependencies will be automatically handled
• Apollo Client configuration is done for you

Minimal Configuration

1. Add nuxt-apollo-client to the modules section of your nuxt.config.ts:

1export default defineNuxtConfig({
2  modules: ['nuxt-apollo-client'],
3  apollo: {
4    endPoints: {
5      default: 'http://localhost:4000/graphql',
6      // Don't change the 'default' key as it is used for the default client
7      // Add more endpoints as needed
8    },
9    // Optional configurations
10    prefix: 'I',
11    tokenKey: 'token',
12    gqlDir: 'graphql',
13  },
14})

2. Create a graphql directory in your project root and add your GraphQL queries and mutations as .ts files.

1// graphql/meQuery.ts
2import gql from 'graphql-tag';
3export const meQuery = gql`
4  query me {
5    me {
6      id
7      name
8    }
9  }
10`;
11
12// graphql/deletePostMutation.ts
13import gql from 'graphql-tag';
14export const deletePostMutation = gql`
15  mutation deletePost($id: ID!) {
16    deletePost(id: $id) {
17      id
18    }
19  }
20

Usage

Use auto-generated composables in your Vue component via auto-imports or import them using the #graphql alias.

Server-side Query (SSR)

Want to fetch data on the server? Just use the await keyword with your query:

1<script setup>
2const { result, loading, error, refetch } = await useMeQuery()
3</script>
4
5<template>
6  <div>Welcome, {{ result?.me?.name }}!</div>
7</template>

This way, your data is ready when the page loads. Great for SEO and initial page load performance!

Client-side Query

For queries that don't need server-side rendering, simply remove the await:

1const { result, loading, error, refetch } = useMeQuery();

Dynamic Refetching Query

You can pass reactive variables such as ref(), reactive(), or computed() to the query, and the hook will automatically refetch the data whenever these variables update. This eliminates the need for manual refetch calls,

1<script setup>
2const userId = ref('1')
3
4const { result, loading, error, refetch } = useGetUserQuery({ id: userId })
5
6const { result, loading, error, refetch } = useGetUserQuery({ id: computed(() => '1') })
7</script>

Multiple Queries

The useMultiQuery composable allows you to combine multiple GraphQL queries—along with their results, loading, and error into a single composable call.

1<script setup lang="ts">
2const { result, loading, error, refetch } = useMultiQuery(
3  ['useGetUsersLazyQuery', 'useMeQuery'], // list of query keys (must match keys in generated composables)
4  {
5    // optional shared variables passed to all queries
6  },
7  {
8    // optional options object, e.g. fetchPolicy, context, etc.
9  }
10)
11
12// Access results
13const users = result.value?.getUsers
14const me = result.value?.me
15
16// Refetch Queries
17const handleRefetch = () => {
18  // Refetch all combined queries
19  refetch(variables)
20
21  // OR: Refetch only specified queries
22  refetch(variables, ['useGetUsersLazyQuery'])
23}
24</script>

Mutations

1<script setup lang="ts">
2const { mutate, loading, error, onDone, onError } = useDeletePostMutation()
3
4const handleDelete = async (id: string) => {
5  await mutate({ id })
6  // Handle successful deletion
7}
8</script>

Configuration Options

Customize it in your nuxt.config.ts file:

Option	Type	Description	Default
endPoints	Record<string, string>	GraphQL endpoint URLs	{ default: 'http://localhost:4000/graphql' }
prefix	string	Prefix for generated types	'I'
tokenKey	string	Key for storing the authentication token	'token'
tokenExpiration	number/Date	When the token expires.	7 days
plugins	string[]	Additional plugins for codegen	[]
pluginConfig	object	Additional configuration for codegen plugins	{}
gqlDir	string	Directory for GraphQL files	'graphql'
runOnBuild	boolean	Run codegen on build	false
enableWatcher	boolean	Enable file watcher for codegen	true
setContext	function	Set context for codegen	({operationName, variables, token}) => any
memoryConfig	InMemoryCacheConfig	Memory cache config for Apollo Client	{}
useGETForQueries	boolean	Use GET for queries	false
apolloClientConfig	ApolloClientOptions<any>	Apollo Client config	null
apolloUploadConfig	ApolloUploadClientOptions	Apollo Upload Client config	`{}
refetchOnUpdate	boolean	Smartly Refetch queries on component, page, or route changes, ideal for dynamic data-driven apps.	false
refetchTimeout	number	Time in milliseconds to wait before refetching a query after a component, page, or route change.	10000
allowOffline	boolean	Runs mutations later if the connection drops.	false

Functions

Function	Description	Syntax
setToken	Sets the token in the cookie	setToken({ key(optional), token, options })
getToken	Gets the token from the cookie	getToken(key(optional))
removeToken	Removes the token from the cookie	removeToken(key(optional), options)
loadApolloClients	Initializes Apollo Clients for use outside components	loadApolloClients()
useKeepCookieAlive	Keeps the auth token cookie alive by updating it periodically	useKeepCookieAlive(debounceMs?: number) (defaults to 10000 ms)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License.