graphql-yoga

GraphQL Yoga is a batteries-included GraphQL server maintained by The Guild, built around the standard WHATWG Fetch API so the same server code runs on Node.js, Deno, Bun, Cloudflare Workers, AWS Lambda, and other JavaScript runtimes without adapter rewrites. createYoga() returns a spec-compliant GraphQL-over-HTTP handler with sensible defaults for GraphiQL, error masking, CORS, file uploads, and subscriptions already wired in, rather than requiring each of those to be assembled from separate packages.

Under the hood, Yoga’s execution pipeline is built on envelop, The Guild’s plugin composition library, so every request passes through a chain of lifecycle hooks (onRequest, onParams, onExecute, onResultProcess, and more) that both Yoga’s own built-in features and third-party envelop plugins can hook into. This gives it the same extensibility model used across The Guild’s GraphQL tooling (GraphQL Mesh, GraphQL Hive) while keeping the default setup close to zero-config for a new project.

Subscriptions are implemented over Server-Sent Events by default (with a GraphQL-over-WebSocket integration package available separately), and the server supports the GraphQL Multipart Request spec for file uploads, automatic persisted queries, and parsing/validation caching out of the box. It is commonly reached for when a team wants a single GraphQL server package that already handles the HTTP-transport details (batching, content negotiation, error formatting) so application code can focus on schema and resolvers.

What You Get

• A createYoga() server factory that returns a WHATWG-Fetch-compatible request handler, so the identical server code deploys to Node, Deno, Bun, Cloudflare Workers, or AWS Lambda
• Built-in GraphiQL IDE served at the GraphQL endpoint for interactive query exploration during development
• Error masking enabled by default, so unexpected server errors are not leaked to clients unless explicitly re-thrown as GraphQLError
• Subscriptions over Server-Sent Events with no extra transport package required for the common case
• File upload support via the GraphQL Multipart Request spec
• Automatic persisted queries and built-in parsing/validation caching for reduced request overhead
• Full extensibility through the envelop plugin ecosystem, letting teams add tracing, auth, rate limiting, or federation without forking the server

Common Use Cases

• Standing up a new GraphQL API quickly with production-sane defaults (error masking, CORS, GraphiQL) instead of hand-assembling them from separate packages
• Deploying the same GraphQL server to multiple runtimes (a Node service in one environment, a Cloudflare Worker at the edge) without maintaining separate server implementations
• Adding GraphQL subscriptions to an existing schema without standing up a separate WebSocket server
• Composing custom request-handling behavior (auth, logging, persisted queries, tracing) via envelop plugins instead of monkey-patching a server’s internals
• Serving as the HTTP layer under a federated or stitched schema built with other GraphQL-Hive/The Guild tooling

Under The Hood

Architecture Request handling flows through createServerAdapter (from @whatwg-node/server) into YogaServer, which builds an envelop-composed execution pipeline in server.ts: incoming requests pass through pluggable request-parser modules (plugins/request-parser/*.ts, one per content type — JSON, GraphQL-over-form-urlencoded, multipart, GET query params) that normalize the transport into GraphQLParams, then through process-request.ts’s processGraphQLParams/processResult functions, which run the actual normalizedExecutor from @graphql-tools/executor and hand the result to a chain of result-processor plugins (plugins/result-processor/{regular,sse}.ts) chosen by content negotiation. Built-in behaviors (health checks, readiness checks, GraphiQL, CORS, masked errors, request validation) are themselves implemented as envelop plugins registered by default in getEnveloped, so the same hook surface (onRequestParse, onParams, onExecute, onResultProcess) that ships Yoga’s own features is what third-party plugins extend — there is no separate “internal” fast path. Swapping the core envelop composition or the WHATWG Fetch polyfill would require touching nearly every plugin file, since they’re all typed against plugins/types.ts’s shared Plugin interface.

Tech Stack Written in strict TypeScript (extending @tsconfig/strictest) as a pnpm-managed monorepo, with the core graphql-yoga package depending on sibling workspace packages (@envelop/core, @envelop/instrumentation, @graphql-yoga/logger, @graphql-yoga/subscription) plus @graphql-tools/executor, @graphql-tools/schema, @graphql-tools/utils, and the @whatwg-node/* family (fetch, server, promise-helpers) that provide the runtime-agnostic Fetch API surface. It peer-depends on graphql 15-17, ships dual CJS/ESM builds via bob (The Guild’s build tool), and is versioned/released through Changesets.

Code Quality Extensive test coverage under packages/graphql-yoga/__tests__ and __integration-tests__ using Jest, with dozens of spec files covering GraphQL-over-HTTP compliance, batching, multipart uploads, subscriptions, error masking, and caching individually rather than as one monolithic suite; several plugin modules also carry colocated .spec.ts files next to their implementation. Error handling is explicit and centralized in error.ts (handleError, isAggregateError, isAbortError), which normalizes thrown values of any shape into GraphQLError instances rather than letting exceptions propagate unformatted. CI (.github/workflows/ci.yml) runs lint, type-check, and tests, and the strictest TypeScript config plus ESLint/Prettier enforce consistent style across the monorepo.

What Makes It Unique Yoga’s defining choice is standardizing entirely on the WHATWG Fetch API (Request/Response) as its execution boundary instead of a Node-specific req/res model, which is what lets one server definition run unmodified across Node, Deno, Bun, and edge/serverless runtimes — a constraint most competing GraphQL servers in the ecosystem don’t share. Combining that with envelop as the plugin substrate means Yoga isn’t a closed server with a fixed feature set but a default composition of the same plugin primitives used elsewhere in The Guild’s GraphQL tooling, so advanced behavior (federation, persisted queries, custom caching) is added by composing more envelop plugins rather than by the server exposing new configuration flags.