Announcing GraphQL Yoga 2.0!

This article was published on Tuesday, March 29, 2022 by Charly Poly @ The Guild Blog

Today we are incredibly excited to share with you the new GraphQL Yoga! This release was made
possible with your contributions, issues, and feedback.

The Guild took over the development of GraphQL Yoga from
Prisma in early 2021, and with the growing community of tools in the GraphQL
space, most recently Envelop, we were able to rewrite GraphQL Yoga 2.0 from
scratch with easy setup, performance, and developer experience at the core.

GraphQL Yoga continues to boast a "convention over configuration" approach and the freedom to use
your favorite libraries, from HTTP to schema-building.

You are no longer required to install dozens of dependencies to get features such as subscriptions,
file uploads, CORS, error masking, and more.

Building a GraphQL Yoga server requires a single import and only a few lines of code to start
serving an API. And you also get GraphiQL for making
development even easier.

// 1. Import GraphQL Yoga
import { createServer } from '@graphql-yoga/node'

// 2. Create your server
const server = createServer({
  schema: {
    typeDefs: /* GraphQL */ `
      type Query {
        hello: String
      }
    `,
    resolvers: {
      Query: {
        hello: () => 'Hello Hello Hello'
      }
    }
  }
})

// 3. Serve the API and GraphiQL
server.start()

The Yoga V2 Experience

Your Stack and Habits

The main goal of Yoga v2 is to allow you to leverage all the GraphQL ecosystem by being
compatible with most of the existing schema-design, HTTP server libraries, and deployment
environments.

Built on top of a modular and extendable GraphQL Server, Yoga v2 allows you to use your
preferred schema design approach and HTTP server library.

For example, Yoga v2 is fully compatible with Express and Nexus, with no additional packages:

import express from 'express'
import { makeSchema, queryType } from 'nexus'
import { createServer } from '@graphql-yoga/node'

const Query = queryType({
  definition(t) {
    t.string('hello', { resolve: () => 'hello world!' })
  }
})
const schema = makeSchema({
  types: [Query]
})

const graphQLServer = createServer({ schema })

const app = express()

// Bind GraphQL Yoga to the `/graphql` endpoint
// Here it takes the request and response objects and handles them internally
app.use('/graphql', graphQLServer)

app.listen(4000, () => {
  console.log('Running a GraphQL API server at http://localhost:4000/graphql')
})

The same applies to GraphQL Tools, Pothos, Nexus, TypeGraphQL, SDL first schema-design approaches,
graphql-js, Apollo Tools, Fastify, Koa, Next.js, SvelteKit, and Deno.

Beyond the compatibility of schema-design and HTTP server libraries, Yoga v2 makes deploying a
GraphQL API to any environment seamless (Vercel Functions, Cloudflare Workers, AWS Lambda and
more).

Here, a GraphQL API built with GraphQL Modules, deployed on Cloudflare Workers:

import { createApplication } from 'graphql-modules'
import { createServer } from '@graphql-yoga/common'
import { helloWorldModule } from './helloWorld'

const application = createApplication({
  modules: [helloWorldModule]
})

const server = createServer({ schema: application.schema })

server.start()

Productivity at Your Fingertips

Batteries-Included

Yoga v2 comes with sensible defaults to make development faster, all with complete TypeScript
support.

Features common to modern GraphQL APIs such as file-uploads, subscription support, advanced
error handling, or CORS come built-in with Yoga:

import { createServer, GraphQLYogaError } from '@graphql-yoga/node'

// Provide your schema
const server = createServer({
  schema: {
    typeDefs: /* GraphQL */ `
      # adding this custom scalar enables file upload support
      scalar Upload

      type Query {
        hello: String
      }

      type Subscription {
        countdown(from: Int!): Int!
      }

      type Mutation {
        readTextFile(file: Upload!): String
      }
    `,
    resolvers: {
      Query: {
        hello: () => 'world'
      },
      Subscription: {
        countdown: {
          // This will return the value on every 1 sec until it reaches 0
          subscribe: async function* (_, { from }) {
            for (let i = from; i >= 0; i--) {
              await new Promise(resolve => setTimeout(resolve, 1000))
              yield { countdown: i }
            }
          }
        }
      },
      Mutation: {
        readTextFile: async (_, { file }: { file: File }) => {
          let textContent = null
          try {
            textContent = await file.text()
          } catch (e) {
            // return an error visible by the client
            throw new GraphQLYogaError(`Failed to parse file`)
          }
          return textContent
        }
      }
    }
  }
})

// We now serve a GraphQL API with Subscriptions (over SSE), CORS,
// and File uploads support!
server.start()

Yoga v2 also provides APIs to handle logging, advanced Subscriptions use-cases (over WS,
Pub/Sub), Apollo Federation Support,
and more.

Easily Extend Your API with Envelop Plugins

GraphQL Yoga supports Envelop out of the box, which gives you greater
control, and the ability to hook into the GraphQL execution phases.

Here, we are building a full-featured GraphQL API with security rules, a response cache and sentry
error reporting with only a few lines of code:

import { useDepthLimit } from '@envelop/depth-limit'
import { useResponseCache } from '@envelop/response-cache'
import { useSentry } from '@envelop/sentry'
import { createServer } from '@graphql-yoga/node'

const server = createServer({
  schema: {
    typeDefs: /* GraphQL */ `
      type Query {
        hello: String
      }
    `,
    resolvers: {
      Query: {
        hello: () => 'Hello Hello Hello'
      }
    }
  },
  plugins: [
    useDepthLimit({
      // set up some security rules
      maxDepth: 10
    }),
    useResponseCache(), // speed up our server with a response cache
    useSentry() // report unexpected errors to sentry
  ]
})

// Start the server and explore http://localhost:4000/graphql
server.start()

The Envelop Plugin currently proposes more than 35+ plugins covering
most of the standard GraphQL APIs features you need in production.

Ultimately, you can develop custom Envelop plugins
to create reusable behaviors that hook on to the GraphQL lifecycle.

Production-Ready

GraphQL Yoga v2 has been built in production for production usage.

Built-in real-world conditions within our projects (e.g. GraphQL Mesh)
and with some of our clients, performance was highly prioritised. The core of Yoga is
as performant as possible, and we continuously keep track and improve it.

Also, the Yoga V2 repository runs performance checks on every commit and Pull Request, so we can
always capture any performance regression.

Last but not least, every commit is ensured to run on all deployment targets such as AWS Lambda or
Cloudflare workers through an End-To-End testing suite!

We continue our effort of pushing GraphQL Yoga to more production environments with the imminent
release of Redwood 1.0 that uses Yoga 2.0 as its default GraphQL server.

A Standards-Compliant GraphQL Server

In the same way that TypeScript aims to stay aligned with ECMAScript, GraphQL Yoga is based on
several official and recognized specs:

GraphQL-spec, GraphQL-over-HTTP: guarantees your GraphQL API to work with all existing GraphQL clients (Apollo, Relay, urql, and more)
GraphQL-Multipart-Request: enables great file upload support
W3C Fetch API: we embrace the future of Node.js and provide the same developer experience on all platforms

GraphQL Features from the Future

Yoga v2 supports some experimental GraphQL features such as
@defer and @stream, allowing you to get a
taste of the future of GraphQL (with compatible clients such as
urql).

Also, thanks to the Envelop plugin system, Yoga v2 can also act as "Babel for GraphQL", giving you
the option to use features that are not yet in the GraphQL spec but are very useful in production
today, like @defer, @stream and
@oneOf.

Get Started with Yoga V2

Yoga v2 provides the best GraphQL experience while giving you the freedom to use your preferred
stack and tools.

Get Started from Scratch with Our New Tutorial

Want to try it? Give
our brand-new tutorial a try! It will
guide you in building a full-featured, modern API with GraphQL Yoga.

Episode #36 of graphql.wtf is also great
introduction to GraphQL Yoga 2.0:

... or Migrate Your Existing GraphQL Server to Yoga

All Yoga v2's features
are well documented on the website, and we also have
some migration guides (from
v1, Apollo Server and Express GraphQL).

What's Next

Yoga v2 is the biggest and most important project we released to date; still, it is just the
beginning of our GraphQL server vision.

We can't wait to get your
questions, user feedback, and feature requests/PRs,
and we already plan for new features such as an Enhanced Plugin System that will provide features
similar to Envelop but at the request level.

Don't hesitate to reach out to us on Twitter and support us by
sharing this article!

Blog