Nuxt GraphQL Client

Common errors

• Failed to load schema from X: Unable to merge GraphQL type "Y": Field "Z" already defined with a different type.

  cause Conflicting type definitions when `graphql-code-generator` attempts to merge schemas from multiple configured GraphQL endpoints.
  fix Ensure that if multiple GraphQL schemas are being consumed, there are no naming conflicts for types or fields, or consider isolating clients to distinct type generation outputs.

• Nuxt instance unavailable error on the server-side.

  cause Attempting to call Nuxt composables (like `useCookie`, `useState`) directly within the `gql:auth:init` hook during server-side rendering, where the Nuxt context is lost.
  fix Refactor your authentication plugin to ensure Nuxt composables are accessed before any `await` statements or before the `gql:auth:init` hook is executed.

• GQL_HOST environment variable is not defined

  cause The GraphQL client host URL has not been provided in the Nuxt configuration or via an environment variable.
  fix Set the `NUXT_PUBLIC_GQL_HOST` environment variable or configure `runtimeConfig.public.graphqlClient.clients.default.host` in your `nuxt.config.ts` file.

• Unexpected token < in JSON at position 0

  cause The GraphQL endpoint returned an HTML error page or another non-JSON response, which the client attempted to parse as JSON.
  fix Verify that your GraphQL API endpoint is correctly configured and returning valid JSON responses, especially for errors. Inspect the network response in developer tools to see the actual content returned by the server.

Warnings

• breaking As a pre-1.0 package (currently 0.2.x), minor version updates of `nuxt-graphql-client` may introduce breaking changes without explicit mention in the release notes. Review changelogs carefully during upgrades.
  Fix: Consult the GitHub releases page and documentation for detailed migration guides between minor versions.
• gotcha Using `localStorage` for token storage does not support Server-Side Rendering (SSR). This can lead to authentication issues or hydration mismatches during the initial server render.
  Fix: Configure `tokenStorage.mode` to `'cookie'` in `nuxt.config.ts` for SSR compatibility.
• gotcha When implementing custom authentication logic via the `gql:auth:init` hook in a Nuxt plugin, direct calls to Nuxt composables like `useState` or `useCookie` inside the hook will result in a 'Nuxt instance unavailable' error on the server-side, due to context loss after the first awaited call.
  Fix: Access Nuxt composables before the `gql:auth:init` hook is invoked, or ensure they are called in a context where the Nuxt instance is guaranteed to be available (e.g., top-level `<script setup>` in a component or directly within a plugin's `setup` function before `await`).
• gotcha When configuring multiple GraphQL clients, schema merging issues can occur if different endpoints define types with the same name but conflicting field definitions (e.g., two `PageInfo` types with `endCursor` having different underlying types). This prevents schema loading during code generation.
  Fix: Inspect the conflicting types and either refactor your GraphQL schemas to avoid naming collisions or use schema stitching/transformation tools outside of `nuxt-graphql-client` to reconcile the schemas before feeding them to the module.

Install

• npm install nuxt-graphql-client npm
• yarn add nuxt-graphql-client yarn
• pnpm add nuxt-graphql-client pnpm

Imports

• useGql

  import { useGql } from '#graphql-client/composables';

  The primary composable for making GraphQL requests. Can be used to create an instance for multiple queries within a non-top-level function.
• useAsyncGql
  wrong:

  import { useGql } from '#graphql-client/composables';

  correct:

  import { useAsyncGql } from '#graphql-client/composables';

  The recommended composable for asynchronously fetching data required to load pages or components, wrapping Nuxt's `useAsyncData`.
• Gql<OperationName>
  wrong:

  import { GetUsers } from '#graphql-client/generated';

  correct:

  const { data } = await GqlGetUsers();

  Automatically generated functions for each named GraphQL operation (Query, Mutation) defined in `.gql` files. For 'query GetUsers', a function `GqlGetUsers` is generated.
• useGqlToken

  import { useGqlToken } from '#graphql-client/composables';

  Composable for setting or clearing authentication tokens for GraphQL requests.
• GqlError

  import { GqlError } from '#graphql-client/types';

  TypeScript type definition for GraphQL errors.

Quickstart

Demonstrates how to configure the module, define a simple GraphQL query in a `.gql` file, and fetch data using the `useAsyncGql` composable within a Nuxt page, complete with loading and error states.

// nuxt.config.ts
import { defineNuxtConfig } from 'nuxt/config';

export default defineNuxtConfig({
  modules: ['nuxt-graphql-client'],
  runtimeConfig: {
    public: {
      graphqlClient: {
        clients: {
          default: {
            host: process.env.NUXT_PUBLIC_GQL_HOST ?? 'https://graphqlzero.almansi.me/api' // Example host
          }
        }
      }
    }
  }
});

// graphql/GetUsers.gql (create this file in your project root or `server/` dir)
query GetUsers($options: PageQueryOptions) {
  users(options: $options) {
    data {
      id
      name
      email
    }
  }
}

// pages/index.vue
<template>
  <div>
    <h1>Users</h1>
    <p v-if="pending">Loading...</p>
    <p v-if="error">Error: {{ error?.message }}</p>
    <ul v-if="data?.users?.data">
      <li v-for="user in data.users.data" :key="user.id">{{ user.name }} ({{ user.email }})</li>
    </ul>
    <button @click="refresh">Refresh</button>
  </div>
</template>

<script setup lang="ts">
// Automatically generated function GqlGetUsers from graphql/GetUsers.gql
const { data, pending, error, refresh } = await useAsyncGql('GetUsers', {
  options: { paginate: { limit: 5 } }
});

// Example of setting an authentication token
// useGqlToken(process.env.NUXT_PUBLIC_AUTH_TOKEN ?? 'your-secret-token');
</script>