mercurius

library16.9.0jsnpmunverified

Mercurius is a GraphQL adapter for Fastify, providing high-performance GraphQL server capabilities including query caching, automatic loader integration to avoid N+1 queries, JIT compilation via graphql-jit, subscriptions, federation support, and a gateway implementation. It is the recommended GraphQL solution for Fastify applications. Current stable version is 16.9.0, released under an active development cadence. It requires Node.js >=20.9.0 or >=22.0.0 and peer dependency graphql ^16.0.0. Key differentiators: tight integration with Fastify, built-in loaders, subscriptions, and federation support.

api

npm install mercurius

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MERCURIUS

mercurius

apijavascriptv16.9.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.

mercurius

✓ import mercurius from 'mercurius'

✗ const mercurius = require('mercurius')

Mercurius ships ESM; default export is the plugin function. For CommonJS, use dynamic import or the require() shown as 'wrong' is actually valid for CJS, but ESM is preferred.

MercuriusOptions

✓ import type { MercuriusOptions } from 'mercurius'

✗ import { MercuriusOptions } from 'mercurius'

MercuriusOptions is a TypeScript type, not a runtime value. Import it with 'import type' or use 'import { MercuriusOptions } from 'mercurius';'. The wrong pattern will fail at runtime if used as value.

MercuriusContext

✓ import type { MercuriusContext } from 'mercurius'

✗ import { MercuriusContext } from 'mercurius'

MercuriusContext is a TypeScript type for context objects. Use 'import type'.

graphql

✓ import { graphql } from 'mercurius'

✗ import graphql from 'mercurius'

The 'graphql' function is a named export, not a default export. It provides a low-level GraphQL execution interface.

Sets up a basic GraphQL server with Fastify and Mercurius, defining a schema and resolvers, handling a GET route with GraphQL query via reply.graphql().

import Fastify from 'fastify' import mercurius from 'mercurius' const app = Fastify() const schema = ` type Query { add(x: Int, y: Int): Int } ` const resolvers = { Query: { add: async (_, { x, y }) => x + y } } await app.register(mercurius, { schema, resolvers }) app.get('/', async function (req, reply) { const query = '{ add(x: 2, y: 2) }' return reply.graphql(query) }) await app.listen({ port: 3000 }) console.log('Server running on port 3000')

Debug

Known issues

breakingMercurius v16 requires Node.js >=20.9.0 or >=22.0.0.

fix

Update Node.js to version 20.9.0 or later, or 22.0.0 or later.

affects: >=16.0.0

breakingMercurius dropped support for graphql@15; requires graphql@^16.0.0.

fix

Upgrade graphql to version 16.x.

affects: >=16.0.0

breakingMercurius v16 is ESM-only. CommonJS require() is not supported.

fix

Use ESM imports (import mercurius from 'mercurius') or dynamic import().

affects: >=16.0.0

deprecatedThe plugin option 'queryDepth' is deprecated; use 'validationRules' instead.

fix

Replace queryDepth with validationRules in plugin options.

affects: >=15.0.0

gotchaUsing 'reply.graphql()' requires that the request has been registered under a Fastify route that has been decorated by Mercurius. Ensure the plugin is registered before calling reply.graphql().

fix

Register Mercurius plugin before routes that use reply.graphql().

affects: >=1.0.0

gotchaWhen using subscriptions, WebSocket upgrade is handled automatically but requires the 'subscription' option set to true and a subscription resolver.

fix

Ensure the 'subscription' option is true and define subscription resolvers.

affects: >=7.0.0

Errors

Common errors & fixes

Error: The module 'mercurius' does not provide a 'default' export

Using `import mercurius from 'mercurius'` with a CommonJS project that doesn't have ESM support.

fix

Either set `"type": "module"` in package.json, or use `const mercurius = require('mercurius')` for CommonJS (though v16 is ESM only, so upgrade Node and use ESM).

TypeError: reply.graphql is not a function

The Mercurius plugin was not registered before the route using reply.graphql().

fix

Ensure `app.register(mercurius, ...)` is called before defining the route that uses reply.graphql.

Error: graphql@15 is not supported. Please upgrade to graphql@^16.

Installed graphql version 15.x, but Mercurius v16 requires graphql 16.x.

fix

Run `npm install graphql@^16` to upgrade.

Error: Cannot find module 'fastify'

Fastify is not installed or not in node_modules.

fix

Install Fastify: `npm install fastify`.

Upgrade

Version history

16.9.0latest on npm

Audit

Dependencies

graphqloptionalPeer dependency; GraphQL schema and execution engine.

Agent activity

41 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/mercurius-js/mercurius ↗

packagemercurius ↗

homepagehttps://mercurius.dev ↗