Registry / database / mercurius-cache

mercurius-cache

JSON →
library8.0.0jsnpmunverified

Adds an in-process or Redis-based caching layer to Mercurius GraphQL server, with deduplication via async-cache-dedupe. Current stable version is 8.0.0, released in 2025. Supports fine-grained per-resolver TTL, stale-while-revalidate, and invalidation. Fully compatible with federation. Unlike generic caching solutions, it integrates directly with Mercurius lifecycle and provides policy-based caching for individual queries or all resolvers. Recommended for production GraphQL APIs needing to reduce load on resolvers with acceptable data staleness.

database
npm install mercurius-cache
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · MERCURIUS-CACHE
M
mercurius-cache
databasejavascriptv8.0.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.

cache
✓ import cache from 'mercurius-cache'
✗ const { cache } = require('mercurius-cache')
Default export. CommonJS: const cache = require('mercurius-cache'). In TypeScript, use default import if esModuleInterop is enabled.

Register Mercurius-Cache with a 10-second TTL, caching only the 'add' resolver.

const fastify = require('fastify'); const mercurius = require('mercurius'); const cache = require('mercurius-cache'); const app = fastify({ logger: true }); const schema = ` type Query { add(x: Int, y: Int): Int hello: String } `; const resolvers = { Query: { async add(_, { x, y }, { reply }) { reply.log.info('add called'); for (let i = 0; i < 10000000; i++) {} // simulate heavy work return x + y; } } }; app.register(mercurius, { schema, resolvers }); app.register(cache, { ttl: 10, policy: { Query: { add: true // only cache 'add', not 'hello' } } }); app.listen(3000); // Test with: curl -X POST -H 'content-type: application/json' -d '{"query":"{ add(x:2, y:2) }"}' localhost:3000/graphql
Debug
Known issues
breakingTTL default changed from undefined to 0 (cache disabled) in v4.
fix
Explicitly set ttl to a positive number to enable caching.
affects: >=4.0.0 <5.0.0
deprecatedThe 'stale' option is deprecated in v6+; use 'stale' at policy level instead.
fix
Move stale to policy-level configuration where needed.
affects: >=6.0.0
gotchaUsing 'all: true' and 'policy' together will cause undefined behavior.
fix
Use only 'all: true' or only 'policy', never both.
affects: >=1.0.0
gotchaThe cache is per resolver by default, not global. Each resolver has its own cache space.
fix
Use Redis storage with shared client for a global cache.
affects: >=1.0.0
breakingRemoved automatic response serialization in v7; cache now stores raw resolver return values.
fix
Ensure resolvers return serializable JSON objects.
affects: >=7.0.0
Errors
Common errors & fixes
Error: mercurius-cache must be registered after mercurius
Mercurius-Cache plugin was registered before the Mercurius plugin.
fix
Ensure app.register(mercurius, ...) is called before app.register(cache, ...).
TypeError: cache is not a function
Using require with destructuring instead of default import.
fix
Use `const cache = require('mercurius-cache');` instead of `const { cache } = require('mercurius-cache');`.
Error: Redis client is required for redis storage
Redis storage type specified but no client provided.
fix
Provide a valid ioredis client: `options.client = new Redis()`.
Upgrade
Version history
8.0.0latest on npm
Audit
Dependencies
fastifyoptionalPeer dependency: Mercurius-Cache is a Fastify plugin
mercuriusoptionalPeer dependency: required GraphQL adapter for Fastify
graphqloptionalPeer dependency: required for GraphQL schema execution
Agent activity
7 hits · last 30 days
node
6
Resources
githubhttps://github.com/mercurius-js/cache ↗
packagemercurius-cache ↗
homepagehttps://github.com/mercurius-js/cache#readme ↗
mercurius-cache — npm install mercurius-cache · libregistry