/api-graphql-yoga

name: api-graphql-yoga
description: GraphQL Yoga v5 server, Envelop plugins, subscriptions, error masking

GraphQL Yoga Patterns

> **Quick Guide:** Use `createYoga` + `createSchema` for a Fetch API-compatible GraphQL server that runs on any JS runtime. Yoga v5 uses Envelop for plugin composition, SSE for subscriptions by default, built-in error masking, and CORS out of the box. Import `GraphQLError` from `graphql` (not `graphql-yoga`) for intentional client-facing errors. Prefer Yoga-specific plugins over Envelop equivalents for HTTP-level optimizations.

---

<critical_requirements>

CRITICAL: Before Using This Skill

**(You MUST import `GraphQLError` from `'graphql'`, NOT from `'graphql-yoga'` -- it is the standard graphql-js export)**

**(You MUST prefer Yoga-specific plugins over Envelop equivalents -- Yoga plugins operate at the HTTP layer and can skip GraphQL execution entirely for cached/persisted results)**

**(You MUST use `createSchema` from `'graphql-yoga'` for schema-first -- passing raw `typeDefs`/`resolvers` objects directly to `createYoga` is not supported in v5)**

**(You MUST use named constants for all numeric values -- timeouts, TTLs, port numbers, limits)**

</critical_requirements>

---

**Auto-detection:** GraphQL Yoga, graphql-yoga, createYoga, createSchema, createPubSub, Envelop, useResponseCache, useCSRFPrevention, usePersistedOperations, GraphQL subscriptions SSE, error masking, maskedErrors, graphql-ws, Yoga plugin hooks, onRequest, onParams

**When to use:**

• Building a GraphQL server that needs to run on Node.js, Bun, Deno, or Cloudflare Workers
• APIs requiring subscriptions via SSE (default) or WebSocket
• Extending GraphQL execution with Envelop plugins (caching, auth, logging)
• File uploads using the GraphQL Multipart Request spec
• Production APIs needing error masking, CORS, and CSRF protection

**When NOT to use:**

• REST-only APIs without GraphQL needs
• Simple CRUD where a framework's built-in route handlers suffice
• When you need a federated gateway (consider a dedicated gateway solution)

**Key patterns covered:**

• Server setup with `createYoga` and `createSchema` (schema-first)
• Type-safe context with generics on `createYoga<ServerContext>`
• Envelop plugin system: lifecycle hooks, custom plugins, Yoga-specific plugins
• Subscriptions: SSE (default), WebSocket via `graphql-ws`, built-in PubSub
• Error masking and intentional `GraphQLError` exposure
• File uploads with WHATWG `File` scalar
• Production hardening: CORS, CSRF prevention, GraphQL Armor, logging
• Cross-runtime deployment: Node.js, Bun, Deno, Cloudflare Workers

**Detailed Resources:**

• [examples/core.md](examples/core.md) - Server setup, schema, context, resolvers, cross-runtime deployment
• [examples/plugins.md](examples/plugins.md) - Envelop plugins, custom plugins, lifecycle hooks
• [examples/subscriptions.md](examples/subscriptions.md) - SSE, WebSocket, PubSub, filtering
• [examples/error-handling.md](examples/error-handling.md) - Error masking, GraphQLError, custom masking
• [examples/production.md](examples/production.md) - CORS, CSRF, response caching, persisted operations, logging
• [reference.md](reference.md) - Decision frameworks, plugin reference, production checklist

---

<philosophy>

Philosophy

GraphQL Yoga is a **batteries-included, Fetch API-compatible GraphQL server**. Its core is built on the WHATWG Fetch API (`Request`/`Response`), making it runtime-agnostic -- the same server code deploys to Node.js, Bun, Deno, and edge runtimes. The Envelop plugin system provides composable middleware at both the HTTP and GraphQL execution layers.

**Schema approach:** Yoga is schema-library agnostic. Use `createSchema` (schema-first SDL), Pothos (code-first), or vanilla `graphql-js` -- anything that produces a `GraphQLSchema` works.

**Plugin priority:** When both an Envelop plugin and a Yoga-specific plugin exist for the same feature (caching, persisted operations, defer/stream), always choose the Yoga variant. Yoga plugins hook into the HTTP layer and can short-circuit before GraphQL execution begins, skipping parsing and validation entirely for cached or persisted results.

**Error philosophy:** All unexpected errors are masked by default in production. Intentional errors are thrown as `GraphQLError` from the `graphql` package -- these bypass masking and reach clients with their message and extensions intact.

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Server Setup with createYoga

Create a Yoga instance with `createSchema` for SDL-based schemas. The yoga instance IS a Fetch API handler -- pass it directly to any runtime's HTTP server.

import { createYoga, createSchema } from "graphql-yoga";
import { createServer } from "node:http";

const PORT = 4000;

const yoga = createYoga({
  schema: createSchema({
    typeDefs: /* GraphQL */ `
      type Query {
        greeting(name: String!): String!
      }
    `,
    resolvers: {
      Query: {
        greeting: (_, { name }) => `Hello, ${name}!`,
      },
    },
  }),
});

const server = createServer(yoga);
server.listen(PORT, () => {
  console.info(`Server running on http://localhost:${PORT}/graphql`);
});

**Why good:** `createSchema` wraps `makeExecutableSchema`, yoga instance is a standard Fetch handler, works on any runtime

See [examples/core.md](examples/core.md) for complete setup, cross-runtime deployment, and type-safe context.

---

Pattern 2: Type-Safe Context

Pass a generic to `createYoga` for server-specific context typing. The `context` factory receives `YogaInitialContext` (containing `request` and `params`) and returns your custom context.

import { createYoga, type YogaInitialContext } from "graphql-yoga";

interface ServerContext {
  req: IncomingMessage;
  res: ServerResponse;
}

const yoga = createYoga<ServerContext>({
  schema,
  context: async ({ request }: YogaInitialContext) => {
    const token = request.headers.get("a