Registry / http-networking / nuxt-graphql-middleware

nuxt-graphql-middleware

library5.4.0jsnpmunverified

Nuxt GraphQL Middleware is an actively developed Nuxt 3 module, currently at version 5.4.0, that streamlines GraphQL integration by acting as a server middleware. It uniquely exposes each GraphQL query and mutation as a fully typed API route, ensuring that GraphQL requests are performed exclusively on the server side, thus keeping GraphQL documents out of the client bundle. The module provides composables like `useGraphqlQuery` and `useAsyncGraphqlQuery` for convenient data fetching within Nuxt applications. It boasts super-fast TypeScript code generation via `graphql-typescript-deluxe`, supports Hot Module Replacement (HMR) for GraphQL files, and includes an integration with the Model Context Protocol (MCP) to expose schema and operations to AI assistants, enabled in dev mode. The project shows a consistent release cadence with frequent patch updates and significant major releases like 5.0.0 which brought build performance improvements and 5.1.0 enforcing Nuxt 3.17+ compatibility. It also integrates with Nuxt DevTools and offers optional client-side caching. Its core differentiator lies in its server-first approach to GraphQL, transforming operations into accessible API endpoints.

http-networking web-framework

npm install nuxt-graphql-middleware

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NUXT-GRAPHQL-MIDDL

nuxt-graphql-middleware

http-networkingjavascriptv5.4.0

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.

useAsyncGraphqlQuery

✓ import { useAsyncGraphqlQuery } from '#imports'

✗ import { useAsyncGraphqlQuery } from 'nuxt-graphql-middleware'

This composable is auto-imported by Nuxt 3, so explicit imports are often not needed in Vue components. Use '#imports' or rely on auto-import for clarity.

useGraphqlQuery

✓ import { useGraphqlQuery } from '#imports'

✗ const useGraphqlQuery = require('nuxt-graphql-middleware')

Similar to useAsyncGraphqlQuery, this is a Nuxt 3 composable and is auto-imported. CommonJS `require()` syntax is incorrect for Nuxt 3 modules.

GraphqlMiddlewareModuleOptions

✓ import type { GraphqlMiddlewareModuleOptions } from 'nuxt-graphql-middleware'

✗ import { GraphqlMiddlewareModuleOptions } from 'nuxt-graphql-middleware'

This is a TypeScript type for configuring the module in `nuxt.config.ts`. Always use `import type` for type-only imports.

defineClientOptions

✓ import { defineClientOptions } from 'nuxt-graphql-middleware/runtime/client-options'

✗ import { defineClientOptions } from 'nuxt-graphql-middleware'

Used in `graphqlMiddleware.clientOptions.ts` files to define client-side context for the middleware. The path is specific.

This example demonstrates how to configure `nuxt-graphql-middleware`, define a GraphQL query in a `.graphql` file, and then use the `useAsyncGraphqlQuery` composable within a Nuxt 3 component to fetch and display data, including handling loading and error states.

// 1. Install the module: // npx nuxi@latest module add nuxt-graphql-middleware // 2. Configure in nuxt.config.ts // import { defineNuxtConfig } from 'nuxt' // export default defineNuxtConfig({ // modules: ['nuxt-graphql-middleware'], // graphqlMiddleware: { // // Replace with your actual GraphQL API endpoint // graphqlEndpoint: process.env.GRAPHQL_ENDPOINT ?? 'https://swapi-graphql.netlify.app/.netlify/functions/index', // // 'dev-only' downloads schema only during `npm run dev` for type generation // downloadSchema: 'dev-only' // } // }) // 3. Create your GraphQL query file, e.g., `assets/queries/films.query.graphql` // query films { // allFilms { // films { // id // title // releaseDate // } // } // } // 4. Use the query in a Vue component, e.g., `pages/index.vue` <template> <div> <h1>Star Wars Films</h1> <p v-if="pending">Loading films...</p> <p v-if="error">Error: {{ error?.message }}</p> <ul v-if="films"> <li v-for="film in films" :key="film.id"> {{ film.title }} ({{ film.releaseDate }}) </li> </ul> <button @click="refresh">Refresh</button> </div> </template> <script setup lang="ts"> // useAsyncGraphqlQuery is auto-imported by Nuxt 3, no explicit import needed in .vue files // For explicit type imports: import type { GraphqlMiddlewareModuleOptions } from 'nuxt-graphql-middleware' interface Film { id: string; title: string; releaseDate: string; } interface FilmsData { allFilms: { films: Film[]; }; } const { data, pending, error, refresh } = await useAsyncGraphqlQuery<FilmsData>('films'); const films = computed(() => data.value?.allFilms?.films || []); // Optional: watch for data changes watch(data, (newValue) => { if (newValue) { console.log('Films loaded:', newValue.allFilms.films.length); } }); // Example of server-side data access (during SSR) if (import.meta.server && data.value) { console.log('Films fetched on server:', data.value.allFilms.films[0]?.title); } </script>

Debug

Known issues

breakingVersion 5.0.0 introduced significant breaking changes primarily affecting the module's build process. While runtime behavior (composables, querying) remained largely consistent, internal build configurations and processes were refactored.

fix

Review the migration guide or new documentation if upgrading from versions prior to 5.0.0, particularly if you have custom build configurations or extensive module hooks.

affects: >=5.0.0

breakingAs of version 5.1.0, `nuxt-graphql-middleware` enforces compatibility with Nuxt versions 3.17.0 and higher. Older Nuxt 3 versions are no longer supported.

fix

Ensure your Nuxt project is running version 3.17.0 or newer. Upgrade your Nuxt installation using `npx nuxi upgrade`.

affects: >=5.1.0

deprecatedSupport for Nuxt 2 was dropped after the 2.x branch. The 3.x and newer releases are exclusively compatible with Nuxt 3. The Nuxt 2 compatible branch (2.x) is no longer maintained.

fix

If using Nuxt 2, you must remain on the 2.x branch of this module (which is unmaintained) or migrate your project to Nuxt 3.

affects: >=3.0.0

gotchaThe behavior of `downloadSchema: true` during `nuxt prepare` was reverted in v5.3.2 after a change in v5.3.0. Additionally, a new option value `'dev-only'` for `downloadSchema` was introduced.

fix

If you experienced issues with schema downloading during `nuxt prepare` after upgrading to 5.3.0, updating to 5.3.2 or newer should resolve it. Consider using `downloadSchema: 'dev-only'` to ensure schema downloading only occurs during development, which is safer than `process.env.NODE_ENV === 'development'`.

affects: >=5.3.0

Errors

Common errors & fixes

Module '#imports' has no exported member 'useAsyncGraphqlQuery'.

Incorrect or missing setup of Nuxt 3 auto-imports, or attempting to use a composable outside a Vue component context.

fix

Ensure your Nuxt 3 project is correctly configured and the module is added to `nuxt.config.ts`. Composables like `useAsyncGraphqlQuery` are primarily for use within `<script setup>` in Vue components or Nuxt plugins.

[nuxt] [error] Failed to download GraphQL schema from 'https://example.com/graphql'.

The configured `graphqlEndpoint` is unreachable, incorrect, or the GraphQL server is not running/responsive during schema download (typically in development or during build prep).

fix

Verify the `graphqlEndpoint` URL in your `nuxt.config.ts` is correct and accessible. Ensure your GraphQL server is running. Check network connectivity and firewall rules. Also, confirm the `downloadSchema` option is correctly configured.

[nuxt] [error] nuxt-graphql-middleware: Missing graphqlEndpoint configuration.

The `graphqlEndpoint` property is not defined within the `graphqlMiddleware` object in your `nuxt.config.ts`.

fix

Add the `graphqlEndpoint` property to your `graphqlMiddleware` configuration in `nuxt.config.ts`, pointing to your GraphQL API server, e.g., `graphqlEndpoint: 'https://api.example.com/graphql'`.

TypeError: Cannot read properties of undefined (reading 'allFilms')

Attempting to access properties of `data.value` before the data has been loaded or if an error occurred during the GraphQL request, causing `data.value` to be `null` or `undefined`.

fix

Always check if `data.value` is defined before accessing its properties. Use optional chaining (`data.value?.allFilms?.films`) or conditional rendering (`<div v-if="data?.value">...</div>`) in your template. Monitor `pending` and `error` states.

Upgrade

Version history

5.4.0latest on npm

Audit

Dependencies

graphqlrequiredCore GraphQL library for schema processing and query execution.

zodrequiredUsed for schema validation and parsing, commonly in type-safe contexts.

@modelcontextprotocol/sdkrequiredRequired for Model Context Protocol (MCP) integration, exposing schema/operations to AI assistants.

@nuxtjs/mcp-toolkitrequiredRequired for Model Context Protocol (MCP) integration, enabling AI assistant features.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/dulnan/nuxt-graphql-middleware ↗

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

homepagehttps://nuxt-graphql-middleware.dulnan.net ↗