Registry / http-networking / nuxt-graphql-client

nuxt-graphql-client

library0.2.46jsnpmunverified

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.

http-networking data web-framework

npm install nuxt-graphql-client

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NUXT-GRAPHQL-CLIEN

nuxt-graphql-client

http-networkingjavascriptv0.2.46

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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

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

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

The recommended composable for asynchronously fetching data required to load pages or components, wrapping Nuxt's `useAsyncData`.

Gql<OperationName>

✓ const { data } = await GqlGetUsers();

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

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.

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>

Debug

Known issues

breakingAs 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.

affects: >=0.2.0

gotchaUsing `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.

affects: >=0.2.0

gotchaWhen 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`).

affects: >=0.2.0

gotchaWhen 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.

affects: >=0.2.0

Errors

Common errors & fixes

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

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.

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

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

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.

Upgrade

Version history

0.2.46latest on npm

Audit

Dependencies

nuxtrequiredPeer dependency, as this is a Nuxt module.

graphql-requestrequiredUnderlying HTTP client for GraphQL operations.

@graphql-codegen/clirequiredUsed for generating TypeScript types and hooks from GraphQL schema and operations.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/diizzayy/nuxt-graphql-client ↗

packagehttps://www.npmjs.com/package/nuxt-graphql-client ↗

homepagehttps://nuxt-graphql-client.web.app ↗