Registry / backend / nuxt-graphql-server

nuxt-graphql-server

library3.1.6jsnpmunverified

Easy GraphQL server implementation for Nuxt 3 with automatic schema merging from .graphql files, typed resolvers via virtual modules, WebSocket subscription support, and Nuxt Devtools integration featuring Apollo Studio Sandbox. Current stable version is 3.1.6, with regular releases on npm. Requires Node >=18.12.0 and peer dependency graphql ^16.7.1. Differentiator: native Nuxt 3 module with zero-config setup, virtual module imports, and devtool integration.

backend

npm install nuxt-graphql-server

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NUXT-GRAPHQL-SERVE

nuxt-graphql-server

backendjavascriptv3.1.6

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

Resolvers

✓ import { Resolvers } from '#graphql/resolver'

✗ import { Resolvers } from 'nuxt-graphql-server'

Virtual module auto-generated by nuxt-graphql-server; do not import from the package itself.

typeDefs

✓ import { typeDefs } from '#graphql/schema'

✗ import typeDefs from '#graphql/schema'

Virtual module; default or named import works, but named import is explicit.

ApolloServer

✓ import { ApolloServer } from '@apollo/server'

✗ import { ApolloServer } from 'apollo-server'

Use @apollo/server v4+; the old apollo-server package is deprecated.

Sets up a minimal GraphQL server in Nuxt 3 with typed resolvers and auto-merged schema.

// nuxt.config.ts export default defineNuxtConfig({ modules: ['nuxt-graphql-server'], }) // server/api/graphql.ts import { Resolvers } from '#graphql/resolver' import { typeDefs } from '#graphql/schema' import { ApolloServer } from '@apollo/server' import { startServerAndCreateH3Handler } from '@as-integrations/h3' const resolvers: Resolvers = { Query: { hello: () => 'world', }, } const apollo = new ApolloServer({ typeDefs, resolvers }) export default startServerAndCreateH3Handler(apollo) // server/schema.graphql (create this file) type Query { hello: String! } // Then run: npx nuxi dev

Debug

Known issues

gotchaVirtual modules (#graphql/schema, #graphql/resolver) are auto-generated only when the module is registered. Ensure nuxt-graphql-server is in modules array.

fix

Add `modules: ['nuxt-graphql-server']` to nuxt.config.ts.

affects: >=3.0.0

gotchaGraphQL schema files must be placed in the `server/` directory and have `.graphql` extension. Files elsewhere are not picked up.

fix

Place .graphql files inside `server/` (e.g., `server/schema.graphql`).

affects: >=3.0.0

breakingv3 dropped support for Nuxt 2; only Nuxt 3 is supported.

fix

Upgrade to Nuxt 3 or use nuxt-graphql-server v2 for Nuxt 2.

affects: >=3.0.0

deprecatedThe default PubSub implementation from graphql-subscriptions is not recommended for production; use a backed implementation like RedisPubSub.

fix

Install graphql-redis-subscriptions or similar and configure PubSub with external store.

affects: >=3.0.0

gotchaFor subscriptions, ensure `nitro.experimental.websocket: true` is set in nuxt.config and install graphql-ws and graphql-subscriptions.

fix

Add experimental websocket config and install extra dependencies.

affects: >=3.0.0

Errors

Common errors & fixes

Cannot find module '#graphql/resolver'

Virtual module not generated because nuxt-graphql-server module is not registered or corrupted.

fix

Ensure `modules: ['nuxt-graphql-server']` is in nuxt.config.ts and the package is installed. Restart Nuxt dev server.

Missing required peer dependency 'graphql'

graphql package not installed.

fix

Run `npm install graphql` or add it to package.json.

TypeError: ApolloServer requires typeDefs

typeDefs from virtual module is empty or not merged correctly.

fix

Check that .graphql files exist in the `server/` directory with valid GraphQL syntax.

WebSocket is not enabled. Set `nitro.experimental.websocket: true` in nuxt.config

Missing Nitro experimental websocket configuration for subscriptions.

fix

Add `nitro: { experimental: { websocket: true } }` to nuxt.config.ts.

Upgrade

Version history

3.1.6latest on npm

Audit

Dependencies

graphqlrequiredPeer dependency for GraphQL schema definitions and execution

@apollo/serverrequiredRuntime dependency for Apollo Server integration (not listed as peer but required in examples)

@as-integrations/h3requiredRuntime dependency connecting Apollo Server with h3 (Nuxt 3 server adapter)

Agent activity

44 hits · last 30 days

node

Resources

githubhttps://github.com/tobiasdiez/nuxt-graphql-server ↗

packagenuxt-graphql-server ↗

homepagehttps://github.com/tobiasdiez/nuxt-graphql-server#readme ↗