graphql-yoga

↗ homepage

weekly downloads759K

versionv5.18.0

licenseMIT

categorybackend

graphqlserverapigraphql-server

Overview

graphql-yoga is a production-ready GraphQL server library built on top of Envelop and designed for modern JavaScript environments. It provides a complete, opinionated solution for building GraphQL APIs with minimal boilerplate while maintaining flexibility through its plugin system. The package consolidates what typically requires multiple dependencies—schema execution, subscriptions, file uploads, CORS, error handling—into a single import that works across Node.js, serverless functions, edge runtimes, and browsers.

The library emerged from the need for a GraphQL server that balances developer experience with performance. Unlike older solutions that require extensive configuration or framework-specific integrations, graphql-yoga uses Web Standards (Fetch API) and provides sensible defaults that work immediately. It achieves significantly lower latency than comparable servers through built-in optimizations like parse/validation caching and optional GraphQL-JIT compilation, while offering native support for modern features like Server-Sent Events subscriptions and Apollo Federation.

With over 759,000 weekly downloads, graphql-yoga has become a go-to choice for teams building everything from microservices to full-stack applications. Its cross-platform architecture means the same code runs in Express, Fastify, AWS Lambda, Cloudflare Workers, or standalone Node.js servers without modification. The Envelop plugin ecosystem provides drop-in functionality for response caching, persisted queries, authorization, rate limiting, and observability—allowing teams to add enterprise features incrementally as requirements evolve.

The v5 release represents a complete rewrite focused on TypeScript-first development, reduced bundle sizes, and improved HTTP-level optimizations. The library maintains full compliance with the GraphQL specification and GraphQL-over-HTTP protocol while adding developer-friendly features like automatic GraphiQL integration, error masking for production environments, and request batching for client migrations.

Quick Start

typescript

import { createServer } from 'node:http'
import { createSchema, createYoga } from 'graphql-yoga'
import { useResponseCache } from '@graphql-yoga/plugin-response-cache'

const typeDefs = /* GraphQL */ `
  type Query {
    user(id: ID!): User
    posts: [Post!]!
  }
  
  type User {
    id: ID!
    name: String!
    email: String!
  }
  
  type Post {
    id: ID!
    title: String!
    author: User!
  }
  
  type Subscription {
    postAdded: Post!
  }
`

const posts = [
  { id: '1', title: 'GraphQL Yoga Introduction', authorId: '1' },
  { id: '2', title: 'Building Scalable APIs', authorId: '2' }
]

const users = [
  { id: '1', name: 'Alice', email: 'alice@example.com' },
  { id: '2', name: 'Bob', email: 'bob@example.com' }
]

const resolvers = {
  Query: {
    user: (_, { id }) => users.find(u => u.id === id),
    posts: () => posts
  },
  Post: {
    author: (post) => users.find(u => u.id === post.authorId)
  },
  Subscription: {
    postAdded: {
      subscribe: async function* () {
        for (const post of posts) {
          yield { postAdded: post }
          await new Promise(resolve => setTimeout(resolve, 2000))
        }
      }
    }
  }
}

const yoga = createYoga({
  schema: createSchema({ typeDefs, resolvers }),
  plugins: [
    useResponseCache({
      session: () => null,
      ttl: 5000
    })
  ],
  cors: {
    origin: ['https://example.com'],
    credentials: true
  },
  maskedErrors: true
})

const server = createServer(yoga)
server.listen(4000, () => {
  console.log('GraphQL API running on http://localhost:4000/graphql')
})

Use Cases

Microservices and serverless GraphQL APIs: Deploy lightweight GraphQL endpoints in AWS Lambda, Cloudflare Workers, or Vercel Edge Functions using the same codebase as your Node.js development environment. The Fetch API-based architecture eliminates runtime-specific code, and built-in cold-start optimizations reduce latency in serverless contexts.

Real-time applications with subscriptions: Implement live data feeds, collaborative editing, or notification systems using native Server-Sent Events support without additional WebSocket infrastructure. The library handles subscription lifecycle, client reconnection, and connection multiplexing automatically, with optional graphql-ws integration for legacy clients.

API gateways with Apollo Federation: Build distributed GraphQL architectures by configuring graphql-yoga as a federation gateway that routes queries across microservices, or as individual subgraphs. The built-in federation support eliminates the need for Apollo Gateway while providing better performance and tighter integration with Yoga's plugin system.

Rapid prototyping and MVPs: Spin up a fully-featured GraphQL API with file uploads, authentication hooks, and development tooling in under 20 lines of code. The batteries-included approach provides CORS, error handling, and GraphiQL out of the box, letting teams validate product ideas without infrastructure investment.

Migration from REST to GraphQL: Use the Sofa plugin to automatically generate REST endpoints from your GraphQL schema with Swagger UI documentation, allowing gradual client migration while maintaining a single source of truth. The persisted operations plugin enables optimized query execution similar to REST endpoints for performance-critical paths.

Pros & Cons

Pros

+Cross-platform architecture runs identically on Node.js, Deno, Bun, browsers, and edge runtimes without code changes or platform-specific adapters
+Exceptional performance with lower latency and higher throughput than Apollo Server in benchmarks, plus optional JIT compilation and automatic caching
+Complete feature set out of the box including subscriptions, file uploads, CORS, error masking, and GraphiQL with no additional dependencies required
+Envelop plugin ecosystem provides production-grade extensions for caching, security, observability, and Apollo Federation with minimal configuration
+Standards-compliant implementation of GraphQL spec, GraphQL-over-HTTP protocol, and W3C Fetch API ensures long-term compatibility and interoperability

Cons

−Smaller ecosystem compared to Apollo Server means fewer third-party integrations and community tutorials, particularly for enterprise tooling
−Plugin-based architecture requires learning Envelop concepts for advanced customization, adding complexity beyond basic schema execution
−Breaking changes between major versions (v2 to v3 to v5) have required migration effort for early adopters, though the API has stabilized in v5

Comparisons

@trpc/server vs graphql-yoga

backend

Install

bash

npm install graphql-yoga

bash

pnpm add graphql-yoga

bash

bun add graphql-yoga

Overview

Quick Start

typescript

import { createServer } from 'node:http'
import { createSchema, createYoga } from 'graphql-yoga'
import { useResponseCache } from '@graphql-yoga/plugin-response-cache'

const typeDefs = /* GraphQL */ `
  type Query {
    user(id: ID!): User
    posts: [Post!]!
  }
  
  type User {
    id: ID!
    name: String!
    email: String!
  }
  
  type Post {
    id: ID!
    title: String!
    author: User!
  }
  
  type Subscription {
    postAdded: Post!
  }
`

const posts = [
  { id: '1', title: 'GraphQL Yoga Introduction', authorId: '1' },
  { id: '2', title: 'Building Scalable APIs', authorId: '2' }
]

const users = [
  { id: '1', name: 'Alice', email: 'alice@example.com' },
  { id: '2', name: 'Bob', email: 'bob@example.com' }
]

const resolvers = {
  Query: {
    user: (_, { id }) => users.find(u => u.id === id),
    posts: () => posts
  },
  Post: {
    author: (post) => users.find(u => u.id === post.authorId)
  },
  Subscription: {
    postAdded: {
      subscribe: async function* () {
        for (const post of posts) {
          yield { postAdded: post }
          await new Promise(resolve => setTimeout(resolve, 2000))
        }
      }
    }
  }
}

const yoga = createYoga({
  schema: createSchema({ typeDefs, resolvers }),
  plugins: [
    useResponseCache({
      session: () => null,
      ttl: 5000
    })
  ],
  cors: {
    origin: ['https://example.com'],
    credentials: true
  },
  maskedErrors: true
})

const server = createServer(yoga)
server.listen(4000, () => {
  console.log('GraphQL API running on http://localhost:4000/graphql')
})

Use Cases

Pros & Cons

Pros

+Cross-platform architecture runs identically on Node.js, Deno, Bun, browsers, and edge runtimes without code changes or platform-specific adapters
+Exceptional performance with lower latency and higher throughput than Apollo Server in benchmarks, plus optional JIT compilation and automatic caching
+Complete feature set out of the box including subscriptions, file uploads, CORS, error masking, and GraphiQL with no additional dependencies required
+Envelop plugin ecosystem provides production-grade extensions for caching, security, observability, and Apollo Federation with minimal configuration
+Standards-compliant implementation of GraphQL spec, GraphQL-over-HTTP protocol, and W3C Fetch API ensures long-term compatibility and interoperability

Cons

−Smaller ecosystem compared to Apollo Server means fewer third-party integrations and community tutorials, particularly for enterprise tooling
−Plugin-based architecture requires learning Envelop concepts for advanced customization, adding complexity beyond basic schema execution
−Breaking changes between major versions (v2 to v3 to v5) have required migration effort for early adopters, though the API has stabilized in v5