GraphQL Yoga: a WHATWG Fetch GraphQL server that runs on Node, Deno, Bun and Workers

What GraphQL Yoga solves, and who it is for

Most JavaScript GraphQL servers start as a Node HTTP framework integration and stay there. GraphQL Yoga starts from the opposite direction. The README states that the core package depends on the WHATWG Fetch API, and that this lets it run and deploy on any environment: serverless, Workers, Deno, Node. The handler is the portable part; the HTTP server is a thin wrapper you supply.

That matters if you ship the same schema to more than one runtime. A team that runs a GraphQL endpoint on Node in development and on Cloudflare Workers in production normally maintains two adapters. With Yoga, the README's quick start creates the Yoga instance once and hands it to node:http's createServer, and the repository's examples/ folder contains separate directories for bun, deno, cloudflare-modules, cloudflare-advanced, aws-lambda, azure-function, firebase, gcp-cloud-run and gcp-functions. The same createYoga call shape is meant to travel across all of them.

The second audience is teams that want subscriptions without running a second WebSocket server. The README lists built-in subscription support over Server-Sent Events, which works through ordinary HTTP infrastructure rather than a separate upgrade path. The third is anyone who already uses Envelop plugins: the README says new GraphQL Yoga supports all envelop plugins, so a plugin you wrote for another Envelop-based server carries over.

How the Fetch handler, schema and plugins fit together

createYoga returns something you can pass directly to an HTTP server constructor. That object is a Fetch handler: it takes a Request and returns a Response. Node's createServer accepts it because Node exposes a compatible request listener interface, but the underlying contract is the web one. That is the whole architectural trick, and it is why the same object works on Workers and Deno, where there is no Node HTTP server to attach to.

The schema is not baked into Yoga. In the README's example, createSchema is imported from graphql-yoga and receives typeDefs and resolvers, producing a schema object that is passed to createYoga under the schema key. Because graphql is a peer dependency you install alongside, you can also build the schema with another tool and hand it over.

Extensions arrive as Envelop plugins. The README points at envelop.dev for the plugin model, and the repository has an examples/envelop/ directory. The feature list names several behaviours that are implemented this way rather than hardcoded: automatic persisted queries, parsing and validation caching, and file uploads following the GraphQL Multipart Request spec. GraphiQL is included and served by default. The README also states Yoga is GraphQL over HTTP spec compliant, with a link to the graphql-http implementations table. If your clients rely on specific HTTP status codes or content negotiation, that compliance is the detail worth verifying against your own client.

Installing GraphQL Yoga and running a first query

The README's install command uses pnpm and installs two packages. graphql-yoga does not bundle graphql, so both are required.

pnpm add graphql-yoga graphql

The README's start example creates a schema inline with createSchema, passes it to createYoga, and wraps the result in a Node HTTP server. Port 4000 is the README's choice, and the log line it prints is http://localhost:4000/graphql.

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

const yoga = createYoga({
  schema: createSchema({
    typeDefs: /* GraphQL */ `
      type Query {
        hello: String
      }
    `,
    resolvers: {
      Query: {
        hello: () => 'Hello from Yoga!'
      }
    }
  })
})

const server = createServer(yoga)

server.listen(4000, () => {
  console.info('Server is running on http://localhost:4000/graphql')
})

Open that URL in a browser and you should get the bundled GraphiQL, not a JSON error. Run the hello query there and the resolver returns the string from the example. If you are not on Node, skip createServer and export the yoga object as your runtime's fetch entry point instead; the examples/ folder has a directory per platform. To work on Yoga itself rather than with it, the README's contributing steps are npm i -g pnpm@8 && pnpm install && pnpm build, with tests under packages/graphql-yoga/__tests__ run by pnpm test. Note that the root package.json declares node >=24 and pnpm >=11 for the monorepo, which is a stricter requirement than using the published package.

Where GraphQL Yoga is the wrong choice

Yoga's portability comes from staying close to plain Fetch. That is also its ceiling. If your organisation has standardised on Apollo Federation for composing subgraphs, or on Apollo Studio for managed federation and schema checks, the README does not claim Yoga replaces that control plane. The repository does contain examples/apollo-federation, examples/apollo-managed-federation and examples/apollo-federation-compatibility, which tells you the project tracks that world closely, but the README itself makes no compatibility promise. Treat the examples as a starting point to read, not as a guarantee.

The second boundary is subscriptions. Yoga implements them over Server-Sent Events. SSE is one-way and rides on normal HTTP, which is why it works in serverless and edge environments where long-lived WebSocket upgrades are awkward or unavailable. If your clients already speak graphql-ws or another WebSocket subscription protocol and you cannot change them, SSE will not match, and the README does not describe a WebSocket transport for the core server.

The third is the Node HTTP server itself. Because the core is a Fetch handler, anything that needs Node-specific request or response behaviour has to come from the surrounding server or a plugin. The examples/express-helmet directory exists for exactly this kind of layering, but it is a layer you add, not something createYoga does for you.

GraphQL Yoga compared with Apollo Server

The related searches around this project repeatedly pair it with Apollo, and the README links to a comparison page in the docs. The difference in approach is structural rather than a feature checklist.

Apollo Server is built around Apollo's own ecosystem: federation composition, managed schema delivery, and a plugin API specific to that server. GraphQL Yoga is built around two external standards instead. The first is WHATWG Fetch, which is what makes the handler portable across Node, Deno, Bun and Workers. The second is Envelop, the plugin layer the README points to, which is shared with other servers rather than owned by Yoga. A plugin written against Envelop is not Yoga-specific.

That produces different migration costs in each direction. Moving to Yoga from another Envelop-based server is mostly a matter of swapping the server construction. Moving to Yoga from Apollo Server means re-examining anything that touches Apollo's plugin interface or its managed federation services. The README's claim of compatibility is limited to GraphQL clients, where it names Apollo, Relay and Urql as clients that work, and to GraphQL over HTTP spec compliance. Client compatibility and server-side ecosystem compatibility are different things, and only the first is stated.

Maintenance, releases and the MIT licence

The repository is not archived, and the last push was on 2026-09-21. Three releases appear in the recent list: release-1789658159962 on 2026-09-17, release-1789573377392 on 2026-09-16, and release-1789141599119 on 2026-09-11. Those release identifiers are generated strings rather than semantic version numbers, so the release list alone does not tell you which version to pin. Check the npm page the README badges link to for the published version before upgrading.

The upgrade cost is shaped by the dependency graph rather than by Yoga's own API. You install graphql-yoga and graphql separately, so a graphql major bump is your decision, not something Yoga forces on you. Plugins come from Envelop, which is a separate package with its own release cadence, so a plugin upgrade can move independently of the server. The repository uses Changesets, visible as the .changeset/ directory and the changeset script in package.json, which means changelog entries are generated per release. Read them before a minor bump if you rely on parsing or validation caching behaviour.

The licence is MIT, stated in both the README and the root package.json. That is a permissive licence, and it is the same licence covering the monorepo's published packages. This is a description of what the repository declares, not legal advice; if your organisation has rules about dependency licences, run them against the actual published package metadata rather than this summary.

Editorial conclusion

Adopt GraphQL Yoga if you want one Fetch-based handler that deploys to Node, Deno, Bun, Cloudflare Workers or AWS Lambda, and if SSE subscriptions and Envelop plugins cover your needs. Do not adopt it if you depend on Apollo Federation composition, Apollo Studio managed federation, or Apollo's subscription transport, because the README does not claim compatibility with those. Before committing, read the comparison page the README links to, check the examples/ folder for the runtime you target, and confirm that graphql-yoga and graphql both resolve in your lockfile, since Yoga does not bundle graphql.

Frequently asked questions

Official sources

1. graphql-hive/graphql-yoga on GitHub
2. License: MIT
3. Project website
4. README
5. Releases