GraphQL Yoga — Batteries-Included GraphQL Server for Node.js

Introduction

GraphQL Yoga is a batteries-included GraphQL server maintained by The Guild. Built on top of the Envelop plugin system and Fetch API standards, it works across Node.js, Deno, Bun, Cloudflare Workers, and AWS Lambda with a consistent API. Yoga handles subscriptions, file uploads, error masking, and CORS out of the box while remaining lightweight and extensible.

What GraphQL Yoga Does

• Serves GraphQL queries, mutations, and subscriptions over HTTP with Server-Sent Events
• Provides a built-in GraphiQL IDE for interactive query development and testing
• Supports multipart file uploads following the GraphQL multipart request specification
• Integrates with any Node.js HTTP framework including Express, Fastify, Koa, and Hapi
• Runs on serverless platforms and edge runtimes via the Fetch API standard

Architecture Overview

Yoga is built on the WHATWG Fetch API, making the core runtime platform-agnostic. It uses The Guild's Envelop library as a plugin system that wraps the GraphQL execution pipeline, allowing plugins to hook into parsing, validation, execution, and result phases. Subscriptions use Server-Sent Events by default, avoiding the complexity of WebSocket setup while maintaining real-time push capabilities.

Self-Hosting & Configuration

• Install graphql-yoga and graphql as npm dependencies in any Node.js project
• Pass a schema (built with createSchema or any GraphQL schema library) to createYoga()
• Integrate with Express via app.use("/graphql", yoga) or mount as a standalone HTTP server
• Configure CORS, logging, and error masking through Yoga constructor options
• Add Envelop plugins for auth, caching, rate limiting, or OpenTelemetry tracing

Key Features

• Zero-config setup with sensible defaults for CORS, error masking, and health checks
• Envelop plugin system provides modular middleware for auth, caching, and observability
• Server-Sent Events for subscriptions work through standard HTTP without WebSocket infrastructure
• Full compatibility with GraphQL Code Generator, Pothos, Nexus, and other schema tools
• Runs identically on Node.js, Deno, Bun, Cloudflare Workers, and AWS Lambda

Comparison with Similar Tools

• Apollo Server — feature-rich GraphQL server with a commercial ecosystem; Yoga is lighter and vendor-neutral
• Mercurius — Fastify-optimized GraphQL server; Yoga is framework-agnostic and supports more runtimes
• Express GraphQL — minimal Express middleware; Yoga provides subscriptions, file uploads, and plugins built-in
• Hono GraphQL — lightweight approach using Hono middleware; Yoga offers a dedicated GraphQL runtime with richer features
• Hasura — auto-generates GraphQL from Postgres; Yoga requires writing resolvers but offers full control over logic

FAQ

Q: How does Yoga handle subscriptions without WebSockets? A: Yoga uses Server-Sent Events (SSE) over standard HTTP, which works through CDNs and load balancers without WebSocket infrastructure. WebSocket transport is available via plugins if needed.

Q: Can I use Yoga with an existing Express or Fastify app? A: Yes. Yoga can be mounted as middleware in Express, Fastify, Koa, Hapi, and other frameworks with a one-line integration.

Q: Does Yoga support schema-first and code-first approaches? A: Yes. Use createSchema with SDL strings for schema-first, or bring schemas from Pothos, Nexus, TypeGraphQL, or any other code-first library.

Q: Is Yoga compatible with Apollo Federation? A: Yes. With the Apollo Federation plugin from Envelop, Yoga can serve as a federated subgraph.

Sources

• https://github.com/dotansimha/graphql-yoga
• https://the-guild.dev/graphql/yoga-server/docs