{"id":17850,"library":"nuxt-graphql-middleware","title":"Nuxt GraphQL Middleware","description":"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.","status":"active","version":"5.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/dulnan/nuxt-graphql-middleware","tags":["javascript","nuxt","nuxt-module","graphql","middleware","typescript","codegen","ssr"],"install":[{"cmd":"npm install nuxt-graphql-middleware","lang":"bash","label":"npm"},{"cmd":"yarn add nuxt-graphql-middleware","lang":"bash","label":"yarn"},{"cmd":"pnpm add nuxt-graphql-middleware","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core GraphQL library for schema processing and query execution.","package":"graphql"},{"reason":"Used for schema validation and parsing, commonly in type-safe contexts.","package":"zod"},{"reason":"Required for Model Context Protocol (MCP) integration, exposing schema/operations to AI assistants.","package":"@modelcontextprotocol/sdk"},{"reason":"Required for Model Context Protocol (MCP) integration, enabling AI assistant features.","package":"@nuxtjs/mcp-toolkit"}],"imports":[{"note":"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.","wrong":"import { useAsyncGraphqlQuery } from 'nuxt-graphql-middleware'","symbol":"useAsyncGraphqlQuery","correct":"import { useAsyncGraphqlQuery } from '#imports'"},{"note":"Similar to useAsyncGraphqlQuery, this is a Nuxt 3 composable and is auto-imported. CommonJS `require()` syntax is incorrect for Nuxt 3 modules.","wrong":"const useGraphqlQuery = require('nuxt-graphql-middleware')","symbol":"useGraphqlQuery","correct":"import { useGraphqlQuery } from '#imports'"},{"note":"This is a TypeScript type for configuring the module in `nuxt.config.ts`. Always use `import type` for type-only imports.","wrong":"import { GraphqlMiddlewareModuleOptions } from 'nuxt-graphql-middleware'","symbol":"GraphqlMiddlewareModuleOptions","correct":"import type { GraphqlMiddlewareModuleOptions } from 'nuxt-graphql-middleware'"},{"note":"Used in `graphqlMiddleware.clientOptions.ts` files to define client-side context for the middleware. The path is specific.","wrong":"import { defineClientOptions } from 'nuxt-graphql-middleware'","symbol":"defineClientOptions","correct":"import { defineClientOptions } from 'nuxt-graphql-middleware/runtime/client-options'"}],"quickstart":{"code":"// 1. Install the module:\n// npx nuxi@latest module add nuxt-graphql-middleware\n\n// 2. Configure in nuxt.config.ts\n// import { defineNuxtConfig } from 'nuxt'\n// export default defineNuxtConfig({\n//   modules: ['nuxt-graphql-middleware'],\n//   graphqlMiddleware: {\n//     // Replace with your actual GraphQL API endpoint\n//     graphqlEndpoint: process.env.GRAPHQL_ENDPOINT ?? 'https://swapi-graphql.netlify.app/.netlify/functions/index',\n//     // 'dev-only' downloads schema only during `npm run dev` for type generation\n//     downloadSchema: 'dev-only'\n//   }\n// })\n\n// 3. Create your GraphQL query file, e.g., `assets/queries/films.query.graphql`\n// query films {\n//   allFilms {\n//     films {\n//       id\n//       title\n//       releaseDate\n//     }\n//   }\n// }\n\n// 4. Use the query in a Vue component, e.g., `pages/index.vue`\n<template>\n  <div>\n    <h1>Star Wars Films</h1>\n    <p v-if=\"pending\">Loading films...</p>\n    <p v-if=\"error\">Error: {{ error?.message }}</p>\n    <ul v-if=\"films\">\n      <li v-for=\"film in films\" :key=\"film.id\">\n        {{ film.title }} ({{ film.releaseDate }})\n      </li>\n    </ul>\n    <button @click=\"refresh\">Refresh</button>\n  </div>\n</template>\n\n<script setup lang=\"ts\">\n// useAsyncGraphqlQuery is auto-imported by Nuxt 3, no explicit import needed in .vue files\n// For explicit type imports: import type { GraphqlMiddlewareModuleOptions } from 'nuxt-graphql-middleware'\n\ninterface Film {\n  id: string;\n  title: string;\n  releaseDate: string;\n}\n\ninterface FilmsData {\n  allFilms: {\n    films: Film[];\n  };\n}\n\nconst { data, pending, error, refresh } = await useAsyncGraphqlQuery<FilmsData>('films');\n\nconst films = computed(() => data.value?.allFilms?.films || []);\n\n// Optional: watch for data changes\nwatch(data, (newValue) => {\n  if (newValue) {\n    console.log('Films loaded:', newValue.allFilms.films.length);\n  }\n});\n\n// Example of server-side data access (during SSR)\nif (import.meta.server && data.value) {\n  console.log('Films fetched on server:', data.value.allFilms.films[0]?.title);\n}\n</script>\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Ensure your Nuxt project is running version 3.17.0 or newer. Upgrade your Nuxt installation using `npx nuxi upgrade`.","message":"As 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.","severity":"breaking","affected_versions":">=5.1.0"},{"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.","message":"Support 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.","severity":"deprecated","affected_versions":">=3.0.0"},{"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'`.","message":"The 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.","severity":"gotcha","affected_versions":">=5.3.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"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.","cause":"Incorrect or missing setup of Nuxt 3 auto-imports, or attempting to use a composable outside a Vue component context.","error":"Module '#imports' has no exported member 'useAsyncGraphqlQuery'."},{"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.","cause":"The configured `graphqlEndpoint` is unreachable, incorrect, or the GraphQL server is not running/responsive during schema download (typically in development or during build prep).","error":"[nuxt] [error] Failed to download GraphQL schema from 'https://example.com/graphql'."},{"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'`.","cause":"The `graphqlEndpoint` property is not defined within the `graphqlMiddleware` object in your `nuxt.config.ts`.","error":"[nuxt] [error] nuxt-graphql-middleware: Missing graphqlEndpoint configuration."},{"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.","cause":"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`.","error":"TypeError: Cannot read properties of undefined (reading 'allFilms')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}