Mercurius
By the Fastify/Mercurius team
Mercurius is a GraphQL adapter for the Fastify web framework that adds GraphQL query execution, subscriptions, and federation support directly into a Fastify application as a plugin. It is built to take advantage of Fastify's…
Definition
Mercurius is a GraphQL adapter for the Fastify web framework that adds GraphQL query execution, subscriptions, and federation support directly into a Fastify application as a plugin. It is built to take advantage of Fastify's performance-oriented architecture, aiming to keep GraphQL request handling as fast as Fastify's own REST request handling. Mercurius is maintained under the same organizational umbrella as Fastify itself.
Overview
Mercurius exists to bring GraphQL support to Fastify applications without giving up the performance characteristics that make Fastify attractive in the first place. Fastify is built around a low-overhead plugin architecture and fast JSON serialization, and many general-purpose GraphQL servers, designed to be framework-agnostic, cannot take full advantage of those framework-specific optimizations. Mercurius is built specifically as a Fastify plugin so it can integrate directly with Fastify's request lifecycle rather than sitting on top of it as an independent HTTP layer. Mechanically, Mercurius is registered as a standard Fastify plugin, and it executes GraphQL operations using the schema and resolvers a developer provides, while adding GraphQL-specific capabilities: support for subscriptions over WebSockets, automatic persisted queries, batched query execution, and GraphQL Federation for composing a schema out of multiple services. It also includes caching mechanisms and a code generation tool for producing TypeScript types from a GraphQL schema, both aimed at reducing manual boilerplate in a Fastify-based GraphQL service. Compared to runtime-agnostic servers like GraphQL Yoga or Apollo Server, which can run on Fastify, Express, or various edge runtimes through adapters, Mercurius takes the opposite approach: it commits to one framework, Fastify, in exchange for deeper integration and, in benchmarks published by its maintainers, competitive request-handling performance. This mirrors the trade-off Fastify itself makes relative to more general frameworks like Express: less portability, more speed within its chosen ecosystem. In practice, Mercurius is chosen by teams already using Fastify for their HTTP layer who want to add a GraphQL API without introducing a second, differently-architected server framework alongside it. It is used for both standalone GraphQL services and for composing federated schemas across multiple Fastify-based microservices. The main limitation of Mercurius is exactly its tight coupling to Fastify: teams not already using Fastify, or that need a GraphQL server portable across multiple runtimes or frameworks, are better served by a framework-agnostic option like GraphQL Yoga or Apollo Server. Mercurius also has a smaller ecosystem and community than Apollo Server, which affects the availability of third-party plugins and community-authored guides for less common scenarios. Because it depends on Fastify's plugin architecture, teams evaluating Mercurius should also budget time to learn Fastify's own conventions, such as its schema-based request validation and encapsulation model, if they are not already familiar with that framework, since Mercurius assumes a working knowledge of Fastify's plugin encapsulation model rather than abstracting it away, and debugging an unfamiliar Fastify error can be an extra hurdle for developers coming from a purely GraphQL-focused background.
Key Features
- Integrates GraphQL execution directly into Fastify as a plugin
- Supports GraphQL subscriptions over WebSockets
- Built-in support for GraphQL Federation across multiple services
- Automatic persisted queries and batched query execution
- TypeScript type generation from a GraphQL schema
- Designed to preserve Fastify's low-overhead request performance