graphql-yoga Documentation

Rewrite of a fully-featured GraphQL Server with focus on easy setup, performance & great developer experience. The core of Yoga implements WHATWG Fetch API...

8,519 stars TypeScript TypeScript 1 file · ~4,021 tokens #bun#deno#fetch#graphql#graphql-server#javascript#nodejs#the-guild
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy graphql-yoga on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run) 
docker run -d --name graphql-yoga -p 4001:4001 --restart always node:24-slim
Configured Services & Ports
⚙️ products
image: node:24-slim
🔌 Ports: 4001:4001
docker-compose.yml
yaml (docker-compose.yml) 
services:
  products:
    image: 'node:24-slim'
    user: 'node'
    working_dir: /web
    environment:
      - NODE_ENV=production
    volumes:
      - ./dist:/web
    command: 'node index.js'
    ports:
      - 4001:4001

File: README.md

Quick start

Install

sh
pnpm add graphql-yoga graphql

Start

Make a schema, create Yoga and start a Node server:

ts
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')
})

Overview

  • Easiest way to run a GraphQL server: Sensible defaults & includes everything you need with
    minimal setup (we also export a platform/env-agnostic handler so you can build your own wrappers
    easily).
  • Includes Subscriptions: Built-in support for GraphQL subscriptions using
    Server-Sent Events.
  • Compatible: Works with all GraphQL clients
    (Apollo, Relay,
    Urql...) and fits seamless in your GraphQL workflow.
  • WHATWG Fetch API: the core package depends on
    WHATWG Fetch API so it can run and deploy on any environment
    (Serverless, Workers, Deno, Node).
  • Easily Extendable: New GraphQL-Yoga support all envelop plugins.

[Features](https://www.the-guild.dev/graphql/yoga-server/docs)

[Documentation](https://www.the-guild.dev/graphql/yoga-server/docs)

Our documentation website will help you get
started.

[Examples](https://github.com/graphql-hive/graphql-yoga/tree/main/examples)

We've made sure developers can quickly start with GraphQL Yoga by providing a comprehensive set of
examples.
See all of them in the examples/ folder.

[Comparison](https://www.the-guild.dev/graphql/yoga-server/docs/comparison)

Read more about how GraphQL Yoga compares to other servers in the ecosystem
here.

Contributing

If this is your first time contributing to this project, please do read our
Contributor Workflow Guide
before you get started off.

For this project in particular, to get started on stage/2-failing-test:

  1. Install Node.js
  2. Run in your terminal: npm i pnpm@8 && pnpm install && pnpm build
  3. Add tests to packages/graphql-yoga/__tests__ using Jest APIs
  4. Run the tests with pnpm test

Feel free to open issues and pull requests. We're always welcome support from the community.

Code of Conduct

Help us keep Yoga open and inclusive. Please read and follow our
Code of Conduct as adopted
from Contributor Covenant.

License

MIT

File: e2e/README.md

Yoga e2e testing

This project contains everything related to e2e testing for GraphQL-Yoga.

In order to ensure that GraphQL-Yoga is compatible with all popular runtimes.

To do that, we are using Pulumi (infrastructure-as-code) (with
TypeScript, and using Automation API) to
provision a real resource in every env, run smoke tests (GET -> GraphiQL,
POST -> Execute GraphQL), and then destroy and remove all resources.

On each PR, this workflow runs, and tried to deploy and test an actual environment. This way we can
find issues like compatibility issues / runtime issues during code reviews.

Tested Enrivonments

Notes

  • This check runs on every PR created to GraphQL-Yoga repo.
  • We are using the locally built version of Yoga - so all functions are deployed as built artifact
    (using esbuild).

File: examples/sveltekit/README.md

GraphQL Yoga - SvelteKit

Learn more

File: examples/subscriptions/README.md

subscriptions

This directory contains a simple GraphQL subscriptions example based on graphql-yoga.

Get started

Clone the repository:

sh
git clone https://github.com/graphcool/graphql-yoga.git
cd graphql-yoga/examples/subscriptions

Install dependencies and run the app:

sh
pnpm install # or npm install
pnpm start   # or npm start

Testing

Counter

Open your browser at http://localhost:4000.

Paste the following subscription in the editor (left side) of GraphiQL:

graphql
subscription {
  counter
}

Press the Play (Execute Query) button.

The counter will increment every second and the corresponding data is received in the Playground:

json
{
  "data": {
    "counter": 1,
  }
}
// ... 1 seconds
{
  "data": {
    "counter": 2,
  }
}
// ... 2 seconds
{
  "data": {
    "counter": 3,
  }
}
// ...

Global counter

Open your browser at http://localhost:4000n.

Paste the following subscription in the editor (left side) of GraphiQL:

graphql
subscription {
  globalCounter
}

Press the Play (Execute Query) button.

You will receive this initial result:

json
{
  "data": {
    "globalCounter": 0
  }
}

Open another browser window and execute the following mutation:

graphql
mutation {
  incrementGlobalCounter
}

Press the Play (Execute Query) button.

You will receive this result:

json
{
  "data": {
    "incrementGlobalCounter": 1
  }
}

On the other window that is executing the subscription, you will receive a new result.

json
{
  "data": {
    "globalCounter": 1
  }
}

As you re-execute the mutation the global counter will be further incremented.

File: examples/service-worker/README.md

Yoga + CloudFlare Worker (bundle)

See e2e testing for more information

For example using CloudFlare Wrangler see this page

File: examples/redis-pub-sub/README.md

Redis Pub/Sub Example

Usage instructions

Start Redis with Docker

bash
docker run -p "6379:6379" redis:7.0.2

Start two server instances running on different ports

bash
PORT=4000 pnpm --filter example-redis-pub-sub start
PORT=4001 pnpm --filter example-redis-pub-sub start

Visit and set up the subscription by pressing the Play button.

bash
http://127.0.0.1:4000/graphql?query=subscription+%7B%0A++message%0A%7D

Visit and execute the mutation by pressing the Play button.

bash
http://127.0.0.1:4001/graphql?query=mutation+%7B%0A++sendMessage%28message%3A+%22Yo+we+share+a+redis+instance.%22%29%0A%7D

See your subscription update appear on 127.0.0.1:4000, even though you executed the mutation on a
different Node.js server instance running on 127.0.0.1:4001.

The magic of Redis. 🪄✨

File: examples/nextjs-ws/README.md

Next.js WebSockets

Get Started

Run the custom server with:

sh
npm start
# or
yarn start
# or
pnpm start

Navigate to http://localhost:3000 to see the Next.js app running. You can
start editing the page by modifying pages/index.js. The page auto-updates as you edit files.

WebSockets cannot be used with
Next.js API Routes, we therefore have to create a
custom Next.js server that will serve the
GraphQL API, WebSockets and the rest of Next.js content.

This custom server implementation can be found in server.js.

Learn More

To learn more about Next.js, take a look at the following resources:

You can check out the Next.js GitHub repository - your
feedback and contributions are welcome!

No deployment on Vercel

Since this Next.js project uses a
custom server, it cannot be deployed to
Vercel.

File: examples/nextjs-legacy-pages/README.md

This is a Next.js project bootstrapped with
create-next-app.

Getting Started

First, run the development server:

bash
npm run dev
# or
pnpm dev

Open http://localhost:3000 with your browser to see the result.

You can start editing the page by modifying pages/index.js. The page auto-updates as you edit the
file.

API routes can be accessed on
http://localhost:3000/api/hello. This endpoint can be edited in
pages/api/hello.js.

The pages/api directory is mapped to /api/*. Files in this directory are treated as
API routes instead of React pages.

Learn More

To learn more about Next.js, take a look at the following resources:

You can check out the Next.js GitHub repository - your
feedback and contributions are welcome!

Deploy on Vercel

The easiest way to deploy your Next.js app is to use the
Vercel Platform
from the creators of Next.js.

Check out our Next.js deployment documentation for more
details.

File: examples/nextjs-auth/README.md

This is a Next.js example using next-auth.js.

Before running this example you need to set upa GitHubOAuth App.
Follow the instructions here.

Use http://localhost:3000/ as the homepage URL.

Use http://localhost:3000/api/auth/callback/github as the authorization callback URL.

Afterwards, you must copy the .env.sample to .env (cp .env.sample .env) and fill in the
environment variables (GITHUB_ID and GITHUB_SECRET) you received from your GitHub OAuth
application.

Run the app with pnpm dev.

You can log in on http://localhost:3000.

Run the following operation on http://localhost:3000/api/graphql.

graphql
query Session {
  session {
    expires
    user {
      id
      email
      image
    }
  }
}

This is a Next.js project bootstrapped with
create-next-app.

Getting Started

First, run the development server:

bash
pnpm dev

Open http://localhost:3000 with your browser to see the result.

You can start editing the page by modifying pages/index.js. The page auto-updates as you edit the
file.

API routes can be accessed on
http://localhost:3000/api/hello. This endpoint can be edited in
pages/api/hello.js.

The pages/api directory is mapped to /api/*. Files in this directory are treated as
API routes instead of React pages.

Learn More

To learn more about Next.js, take a look at the following resources:

You can check out the Next.js GitHub repository - your
feedback and contributions are welcome!

Deploy on Vercel

The easiest way to deploy your Next.js app is to use the
Vercel Platform
from the creators of Next.js.

Check out our Next.js deployment documentation for more
details.

File: examples/nextjs-app/README.md

This is a Next.js project bootstrapped with
create-next-app.

Getting Started

First, run the development server:

bash
npm run dev
# or
yarn dev
# or
pnpm dev

Open http://localhost:3000 with your browser to see the result.

You can start editing the page by modifying app/page.tsx. The page auto-updates as you edit the
file.

This project uses next/font to
automatically optimize and load Inter, a custom Google Font.

Learn More

To learn more about Next.js, take a look at the following resources:

You can check out the Next.js GitHub repository - your
feedback and contributions are welcome!

Deploy on Vercel

The easiest way to deploy your Next.js app is to use the
Vercel Platform
from the creators of Next.js.

Check out our Next.js deployment documentation for more
details.

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#bun Browse bun catalog → #deno Browse deno catalog → #fetch Browse fetch catalog → #graphql Browse graphql catalog → #graphql-server Browse graphql-server catalog → #javascript Browse javascript catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →