{"id":15733,"library":"nuxt-graphql-client","title":"Nuxt GraphQL Client","description":"nuxt-graphql-client is a comprehensive Nuxt 3 module designed to integrate GraphQL client capabilities with built-in code generation. Currently at version 0.2.46, the package sees frequent patch releases, indicating active development and responsiveness to bug fixes and minor feature enhancements. It leverages `graphql-request` for executing GraphQL operations and `graphql-code-generator` to automatically generate TypeScript types and composables (`useGql`, `useAsyncGql`, `Gql<OperationName>`) directly from your GraphQL schema and `.gql` files. This approach ensures full TypeScript support and Hot Module Reload (HMR) for GraphQL documents. Its key differentiators include a 'zero configuration' option for rapid setup, deep integration with the Nuxt 3 reactivity system and composables, and streamlined developer experience by automating boilerplate for GraphQL interactions, providing a modern alternative to more manually configured GraphQL client setups in Nuxt applications.","status":"active","version":"0.2.46","language":"javascript","source_language":"en","source_url":"https://github.com/diizzayy/nuxt-graphql-client","tags":["javascript","vue","nuxt","nuxt3","nuxt-module","gql","graphql","graphql-client","graphql-request","typescript"],"install":[{"cmd":"npm install nuxt-graphql-client","lang":"bash","label":"npm"},{"cmd":"yarn add nuxt-graphql-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add nuxt-graphql-client","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency, as this is a Nuxt module.","package":"nuxt","optional":false},{"reason":"Underlying HTTP client for GraphQL operations.","package":"graphql-request","optional":false},{"reason":"Used for generating TypeScript types and hooks from GraphQL schema and operations.","package":"@graphql-codegen/cli","optional":false}],"imports":[{"note":"The primary composable for making GraphQL requests. Can be used to create an instance for multiple queries within a non-top-level function.","symbol":"useGql","correct":"import { useGql } from '#graphql-client/composables';"},{"note":"The recommended composable for asynchronously fetching data required to load pages or components, wrapping Nuxt's `useAsyncData`.","wrong":"import { useGql } from '#graphql-client/composables';","symbol":"useAsyncGql","correct":"import { useAsyncGql } from '#graphql-client/composables';"},{"note":"Automatically generated functions for each named GraphQL operation (Query, Mutation) defined in `.gql` files. For 'query GetUsers', a function `GqlGetUsers` is generated.","wrong":"import { GetUsers } from '#graphql-client/generated';","symbol":"Gql<OperationName>","correct":"const { data } = await GqlGetUsers();"},{"note":"Composable for setting or clearing authentication tokens for GraphQL requests.","symbol":"useGqlToken","correct":"import { useGqlToken } from '#graphql-client/composables';"},{"note":"TypeScript type definition for GraphQL errors.","symbol":"GqlError","correct":"import { GqlError } from '#graphql-client/types';"}],"quickstart":{"code":"// nuxt.config.ts\nimport { defineNuxtConfig } from 'nuxt/config';\n\nexport default defineNuxtConfig({\n  modules: ['nuxt-graphql-client'],\n  runtimeConfig: {\n    public: {\n      graphqlClient: {\n        clients: {\n          default: {\n            host: process.env.NUXT_PUBLIC_GQL_HOST ?? 'https://graphqlzero.almansi.me/api' // Example host\n          }\n        }\n      }\n    }\n  }\n});\n\n// graphql/GetUsers.gql (create this file in your project root or `server/` dir)\nquery GetUsers($options: PageQueryOptions) {\n  users(options: $options) {\n    data {\n      id\n      name\n      email\n    }\n  }\n}\n\n// pages/index.vue\n<template>\n  <div>\n    <h1>Users</h1>\n    <p v-if=\"pending\">Loading...</p>\n    <p v-if=\"error\">Error: {{ error?.message }}</p>\n    <ul v-if=\"data?.users?.data\">\n      <li v-for=\"user in data.users.data\" :key=\"user.id\">{{ user.name }} ({{ user.email }})</li>\n    </ul>\n    <button @click=\"refresh\">Refresh</button>\n  </div>\n</template>\n\n<script setup lang=\"ts\">\n// Automatically generated function GqlGetUsers from graphql/GetUsers.gql\nconst { data, pending, error, refresh } = await useAsyncGql('GetUsers', {\n  options: { paginate: { limit: 5 } }\n});\n\n// Example of setting an authentication token\n// useGqlToken(process.env.NUXT_PUBLIC_AUTH_TOKEN ?? 'your-secret-token');\n</script>","lang":"typescript","description":"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."},"warnings":[{"fix":"Consult the GitHub releases page and documentation for detailed migration guides between minor versions.","message":"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.","severity":"breaking","affected_versions":">=0.2.0"},{"fix":"Configure `tokenStorage.mode` to `'cookie'` in `nuxt.config.ts` for SSR compatibility.","message":"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.","severity":"gotcha","affected_versions":">=0.2.0"},{"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`).","message":"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.","severity":"gotcha","affected_versions":">=0.2.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.2.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"Conflicting type definitions when `graphql-code-generator` attempts to merge schemas from multiple configured GraphQL endpoints.","error":"Failed to load schema from X: Unable to merge GraphQL type \"Y\": Field \"Z\" already defined with a different type."},{"fix":"Refactor your authentication plugin to ensure Nuxt composables are accessed before any `await` statements or before the `gql:auth:init` hook is executed.","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.","error":"Nuxt instance unavailable error on the server-side."},{"fix":"Set the `NUXT_PUBLIC_GQL_HOST` environment variable or configure `runtimeConfig.public.graphqlClient.clients.default.host` in your `nuxt.config.ts` file.","cause":"The GraphQL client host URL has not been provided in the Nuxt configuration or via an environment variable.","error":"GQL_HOST environment variable is not defined"},{"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.","cause":"The GraphQL endpoint returned an HTML error page or another non-JSON response, which the client attempted to parse as JSON.","error":"Unexpected token < in JSON at position 0"}],"ecosystem":"npm"}