# GraphQL Yoga — Batteries-Included GraphQL Server for Node.js

> GraphQL Yoga is a fully-featured GraphQL server by The Guild with built-in subscriptions, file uploads, and compatibility with any HTTP framework or serverless platform.

## Install

Save in your project root:

# GraphQL Yoga — Batteries-Included GraphQL Server for Node.js

## Quick Use
```bash
npm install graphql-yoga graphql
```
```typescript
import { createServer } from "node:http";
import { createSchema, createYoga } from "graphql-yoga";

const yoga = createYoga({
  schema: createSchema({
    typeDefs: `type Query { hello: String }`,
    resolvers: { Query: { hello: () => "Hello from Yoga!" } },
  }),
});
createServer(yoga).listen(4000, () => console.log("Running on http://localhost:4000/graphql"));
```

## Introduction
GraphQL Yoga is a batteries-included GraphQL server maintained by The Guild. Built on top of the Envelop plugin system and Fetch API standards, it works across Node.js, Deno, Bun, Cloudflare Workers, and AWS Lambda with a consistent API. Yoga handles subscriptions, file uploads, error masking, and CORS out of the box while remaining lightweight and extensible.

## What GraphQL Yoga Does
- Serves GraphQL queries, mutations, and subscriptions over HTTP with Server-Sent Events
- Provides a built-in GraphiQL IDE for interactive query development and testing
- Supports multipart file uploads following the GraphQL multipart request specification
- Integrates with any Node.js HTTP framework including Express, Fastify, Koa, and Hapi
- Runs on serverless platforms and edge runtimes via the Fetch API standard

## Architecture Overview
Yoga is built on the WHATWG Fetch API, making the core runtime platform-agnostic. It uses The Guild's Envelop library as a plugin system that wraps the GraphQL execution pipeline, allowing plugins to hook into parsing, validation, execution, and result phases. Subscriptions use Server-Sent Events by default, avoiding the complexity of WebSocket setup while maintaining real-time push capabilities.

## Self-Hosting & Configuration
- Install graphql-yoga and graphql as npm dependencies in any Node.js project
- Pass a schema (built with createSchema or any GraphQL schema library) to createYoga()
- Integrate with Express via app.use("/graphql", yoga) or mount as a standalone HTTP server
- Configure CORS, logging, and error masking through Yoga constructor options
- Add Envelop plugins for auth, caching, rate limiting, or OpenTelemetry tracing

## Key Features
- Zero-config setup with sensible defaults for CORS, error masking, and health checks
- Envelop plugin system provides modular middleware for auth, caching, and observability
- Server-Sent Events for subscriptions work through standard HTTP without WebSocket infrastructure
- Full compatibility with GraphQL Code Generator, Pothos, Nexus, and other schema tools
- Runs identically on Node.js, Deno, Bun, Cloudflare Workers, and AWS Lambda

## Comparison with Similar Tools
- **Apollo Server** — feature-rich GraphQL server with a commercial ecosystem; Yoga is lighter and vendor-neutral
- **Mercurius** — Fastify-optimized GraphQL server; Yoga is framework-agnostic and supports more runtimes
- **Express GraphQL** — minimal Express middleware; Yoga provides subscriptions, file uploads, and plugins built-in
- **Hono GraphQL** — lightweight approach using Hono middleware; Yoga offers a dedicated GraphQL runtime with richer features
- **Hasura** — auto-generates GraphQL from Postgres; Yoga requires writing resolvers but offers full control over logic

## FAQ
**Q: How does Yoga handle subscriptions without WebSockets?**
A: Yoga uses Server-Sent Events (SSE) over standard HTTP, which works through CDNs and load balancers without WebSocket infrastructure. WebSocket transport is available via plugins if needed.

**Q: Can I use Yoga with an existing Express or Fastify app?**
A: Yes. Yoga can be mounted as middleware in Express, Fastify, Koa, Hapi, and other frameworks with a one-line integration.

**Q: Does Yoga support schema-first and code-first approaches?**
A: Yes. Use createSchema with SDL strings for schema-first, or bring schemas from Pothos, Nexus, TypeGraphQL, or any other code-first library.

**Q: Is Yoga compatible with Apollo Federation?**
A: Yes. With the Apollo Federation plugin from Envelop, Yoga can serve as a federated subgraph.

## Sources
- https://github.com/dotansimha/graphql-yoga
- https://the-guild.dev/graphql/yoga-server/docs

---
Source: https://tokrepo.com/en/workflows/asset-0499ec1b
Author: AI Open Source