GraphQL Yoga

Overview

GraphQL Yoga (v5) is a spec-compliant GraphQL server built on the WHATWG Fetch API, so the same yoga object works as a Node http handler, a Fetch handler (yoga.fetch) in Workers, Bun and Deno, or behind Express, Fastify and Next.js. It is extended with Envelop plugins. It ships with GraphQL over SSE subscriptions, multipart file uploads, CORS, GraphiQL and error masking; you add caching, rate limiting and depth limits as plugins. Schemas can be written with createSchema (SDL plus resolvers) or with code-first builders such as Pothos.

Instructions

1. Install: npm install graphql-yoga graphql.
2. Build the schema with createSchema({ typeDefs, resolvers }), pass it to createYoga, and hand the result to createServer from node:http. The endpoint defaults to /graphql; change it with graphqlEndpoint.
3. Per-request state (database handle, current user) goes in the context option, which receives { request } (a Fetch Request) plus runtime-specific fields such as req/res on Node.
4. Subscriptions: use createPubSub() exported by graphql-yoga; pubSub.publish(topic, payload) and pubSub.subscribe(topic) (an async iterable). Clients connect over SSE by default; no WebSocket server is needed. For several instances, back the pub/sub with Redis using @graphql-yoga/redis-event-target.
5. File uploads: declare scalar File in the schema and accept File! arguments. The value is a standard File/Blob (.text(), .arrayBuffer(), .stream()). Multipart parsing is on by default; multipart: false turns it off.
6. Errors: Yoga masks unexpected errors by default. Throw GraphQLError (from graphql) with extensions.code for errors clients should see. maskedErrors: false disables masking (development only). With NODE_ENV=development the original error appears in extensions.originalError.
7. GraphiQL is enabled only in development by default; set graphiql: false or a function to control it.
8. Plugins go in plugins: []. Packages verified to exist:
   • @graphql-yoga/plugin-response-cache exports useResponseCache({ session, ttl, invalidateViaMutation }); ttl is milliseconds, session returns a string per user or null for a global cache.
   • @envelop/rate-limiter exports useRateLimiter({ identifyFn }); limits are declared in the schema with the @rateLimit(max: 10, window: "5s") directive (you must define the directive in your SDL).
   • @envelop/depth-limit exports useDepthLimit({ maxDepth }). @escape.tech/graphql-armor-max-depth is an alternative.