Configuration

nuxt-graphql-client is configured by default to cover most use cases, this can be overridden by passing custom configuration to the graphql-client property in either runtime configuration or directly in nuxt.config.ts.

Options

  • Defaults
export default defineNuxtConfig({
    'graphql-client':{
        watch: true,
        autoImport: true,
        functionPrefix: 'Gql',
        documentPaths: ['./'],
        preferGETQueries: false
    }
})

watch

  • default: true

Enable hot reloading for GraphQL documents

autoImport

  • default: true

Auto import functions based on the operation name of your queries & mutations

functionPrefix

  • default: Gql

Prefix for auto imported functions

documentPaths

Path to external folder(s) containing .gql or .graphql files.

Example: ['../shared/queries']

Useful for mono repos.

preferGETQueries

  • default: false

When enabled, all queries will be sent as GET requests. This flag can be overridden on a per-client basis.

Code Generation

Configuration for the GraphQL Code Generator, setting codegen: false disables codegen and results in limited TypeScript support.

export default defineNuxtConfig({
    'graphql-client': {
        codegen: {
            silent: true,
            skipTypename: true,
            useTypeImports: true,
            dedupeFragments: true,
            onlyOperationTypes: true,
            avoidOptionals: false,
            disableOnBuild: false,
            maybeValue: 'T | null'
        }
    }
})

silent

  • default: true

Prevent GraphQL Code Generator from printing to console

skipTypename

  • default: true

Prevent adding __typename to generated types.

useTypeImports

  • default: true

Use import type {} rather than import {} when importing only types.

dedupeFragments

  • default: true

Removes fragment duplicates. It is done by removing sub-fragments imports from fragment definition Instead - all of them are imported to the Operation node.

onlyOperationTypes

  • default: true

Only generate the types for the operations in your GraphQL documents. When set to true, only the types needed for your operations will be generated. When set to false, all types from the GraphQL API will be generated.

avoidOptionals

  • default: false

Avoid using TypeScript optionals on types. See GraphQL Code Generator documentation for more options

disableOnBuild

  • default: false

Disable Code Generation for production builds.

maybeValue

  • default: "T | null"

Allow to override the type value of Maybe. See GraphQL Code Generator documentation for more options

Client configuration

The default client overrides GQL_HOST.
  • Type: object

Configure your app to interact with multiple GraphQL APIs. The name of each client is the key of the object provided.

The available options are:

host

URL of the GraphQL API.

clientHost

Specify a host to be used for client side requests.

introspectionHost

Specify a host to be used for GraphQL Codegen introspection.

schema

Specify the path to a GraphQL Schema file to be used for code generation. When omitted, the host will be used.

token

Configure a token to be used for authentication.

This flag accepts either a string, or an object to further configure the token.

nuxt.config.ts
'graphql-client': {
    clients: {
        default: {
            host: '<graphql_api>',

            // Basic
            token: '<auth_token>',

            // Advanced
            token: {
                type: 'Bearer',
                name: 'Authorization',
                value: '<auth_token>'
            }
        }
    }
}

retainToken

  • default: false

When enabled, this flag will force tokens set at config-level to be retained client-side.

By default, tokens set by runtimeConfig or environment variables only live server-side (for Code Generation & SSR requests).

More information here

proxyCookies

  • default: true

Pass cookies from the browser to the GraphQL API in SSR mode.

Enabled by default.

proxyHeaders

Headers to be passed from the browser to the GraphQL API in SSR mode.

corsOptions

Specify CORS options to be used for client-side requests.

Type Signature
{ 
    corsOptions: {
      mode: "cors" | "navigate" | "no-cors" | "same-origin"
      credentials: "include" | "omit" | "same-origin"
    }
}

preferGETQueries

  • default: false

When enabled, all queries for this client will be sent as GET requests.

headers

Configure default headers to be sent with each request on both client and server side. The serverOnly property is used to declare headers that should only be applied on server-side. e.g.:

'graphql-client': {
    clients: {
        default: {
            host: '<graphql_api>',
            headers: {
                'X-CUSTOM-HEADER': '',
                serverOnly: {
                    'X-SERVER-ONLY': ''
                }
            }
        }
    }
}

codegenHeaders

Specify headers that should be applied during development code generation. This is useful in cases where various queries / mutations are only available based on authorization or when other special headers are passed.

'graphql-client': {
    clients: {
        default: {
            host: '<graphql_api>',
            codegenHeaders: {
                'X-CUSTOM-HEADER': ''
            }
        }
    }
}

tokenStorage

  • default: true

Configuration for the token storage.

Type Signature
{ 
    name: 'gql:<clientname>'
    mode: 'cookie' | 'localStorage'
    cookieOptions: {
        path: string
        domain: string
        maxAge: number
        secure: boolean
        httpOnly: boolean
        sameSite: 'lax' | 'strict' | 'none'
    }
}

fetchOptions

Specify additional fetch options to configure the GraphQL client.

More information here

'graphql-client': {
    clients: {
        default: {
            host: '<graphql_api>',
            fetchOptions: {
                errorPolicy: 'ignore' // Ignore incoming errors and resolve like no errors occurred
            }
        }
    }
}