nitro-graphql

library1.8.0jsnpmunverified

GraphQL integration for Nitro, the universal JavaScript server framework built on h3. Version 1.8.0 is current; releases are stable but infrequent. It bridges Apollo Server 5 with Nitro via @as-integrations/h3, enabling declarative GraphQL endpoints with zero-config setup. Differentiates from manual Apollo integration by handling middleware, context, and error handling out of the box. Requires nitropack 2.x and h3 1.x. Ships TypeScript types.

devops api

npm install nitro-graphql

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NITRO-GRAPHQL

nitro-graphql

devopsjavascriptv1.8.0

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.

createGraphqlEvent

✓ import { createGraphqlEvent } from 'nitro-graphql/event'

✗ import { createGraphqlEvent } from 'nitro-graphql'

Function exported from subpath 'nitro-graphql/event', not the main module.

defineGraphqlConfig

✓ import { defineGraphqlConfig } from 'nitro-graphql'

✗ import { defineGraphqlConfig } from 'nitro-graphql/config'

Main export function for configuration.

nitroGraphqlPlugin

✓ import { nitroGraphqlPlugin } from 'nitro-graphql'

✗ import { nitroGraphqlPlugin } from 'nitro-graphql/plugin'

Plugin exported from main module.

Configures GraphQL schema and resolvers in a Nitro app using the plugin, with context injection.

// nitro.config.ts import { defineNitroConfig } from 'nitropack/config'; import { defineGraphqlConfig } from 'nitro-graphql'; export default defineNitroConfig({ plugins: ['nitro-graphql/plugin'], graphql: { schema: './schema.graphql', // path to your schema resolvers: './resolvers', // directory with resolver files context: (event) => ({ user: event.context.user }), }, }); // server/plugins/graphql.ts import { defineNitroPlugin } from 'nitropack/runtime'; import { nitroGraphqlPlugin } from 'nitro-graphql'; export default defineNitroPlugin((nitroApp) => { nitroGraphqlPlugin(nitroApp); }); // resolver example: server/graphql/resolvers/hello.ts export default { Query: { hello: () => 'Hello world!' } };

Debug

Known issues

gotchaThe plugin must be registered both in nitro.config.ts plugins array and as a Nitro plugin in server/plugins/graphql.ts. Missing either results in GraphQL endpoint not being created.

fix

Add 'nitro-graphql/plugin' to plugins array in nitro.config.ts and import/register nitroGraphqlPlugin in a Nitro plugin file.

affects: >=1.0.0

gotchaThe context option in defineGraphqlConfig expects a function that receives an H3 event and returns an object. If you use an async function, it must return a Promise. Not returning an object will cause runtime errors.

fix

Ensure context function returns an object synchronously or via Promise.

affects: >=1.0.0

deprecatedUsing 'nitro-graphql' without specifying 'schema' and 'resolvers' in config is deprecated and will be removed in v2.0. You must provide both.

fix

Specify 'schema' (string path or GraphQL schema) and 'resolvers' (path to directory or resolver map) in your graphql config.

affects: >=1.5.0

gotchaWhen using TypeScript, you must install @types/node and ensure tsconfig.json has 'moduleResolution': 'node' or 'bundler' to resolve subpath exports correctly.

fix

Add 'moduleResolution': 'node' in tsconfig.json and install @types/node as devDependency.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Could not resolve "nitro-graphql/event" (imported by ...). Did you mean to import "nitro-graphql/event.js"?

Using subpath export without explicit extension in a Node.js environment with strict module resolution.

fix

Import with extension: import { createGraphqlEvent } from 'nitro-graphql/event.js'

TypeError: (0 , nitro_graphql__WEBPACK_IMPORTED_MODULE_0__.nitroGraphqlPlugin) is not a function

The plugin was not imported correctly or the package is not properly installed.

fix

Verify import: import { nitroGraphqlPlugin } from 'nitro-graphql'. Ensure package is installed and not corrupted. Check for conflicting exports.

GraphQLError: Schema must be provided or build from resolvers.

Missing 'schema' and 'resolvers' in graphql config.

fix

Add 'schema' and 'resolvers' options to defineGraphqlConfig. Example: graphql: { schema: './schema.graphql', resolvers: './resolvers' }

Upgrade

Version history

1.8.0latest on npm

Audit

Dependencies

h3requiredpeer dependency for HTTP server framework

graphqlrequiredpeer dependency for GraphQL runtime

nitropackrequiredpeer dependency for Nitro server framework

@apollo/serverrequiredpeer dependency for Apollo Server integration

@as-integrations/h3requiredpeer dependency for Apollo Server + h3 adapter

@apollo/utils.withrequiredrequiredpeer dependency for Apollo utility

Agent activity

53 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/productdevbook/nitro-graphql ↗

packagenitro-graphql ↗

homepagehttps://github.com/productdevbook/nitro-graphql#readme ↗