graphql-yoga

What is graphql-yoga?

graphql-yoga is a fully-featured GraphQL server that is easy to set up and use. It is built on top of GraphQL.js and provides a simple yet powerful API for building GraphQL servers. It comes with out-of-the-box support for features like subscriptions, file uploads, and more.

What are graphql-yoga's main functionalities?

Basic Server Setup

This code sets up a basic GraphQL server with a single query 'hello' that returns a string. The server is started and listens on port 4000.

const { createServer } = require('graphql-yoga');
const typeDefs = `
  type Query {
    hello: String!
  }
`;
const resolvers = {
  Query: {
    hello: () => 'Hello, world!',
  },
};
const server = createServer({ typeDefs, resolvers });
server.start(() => console.log('Server is running on http://localhost:4000'));

Subscriptions

This code demonstrates how to set up a GraphQL server with subscriptions. It uses the 'graphql-subscriptions' package to handle real-time updates. A new message is published every second.

const { createServer } = require('graphql-yoga');
const { PubSub } = require('graphql-subscriptions');
const pubsub = new PubSub();
const typeDefs = `
  type Query {
    hello: String!
  }
  type Subscription {
    newMessage: String!
  }
`;
const resolvers = {
  Query: {
    hello: () => 'Hello, world!',
  },
  Subscription: {
    newMessage: {
      subscribe: () => pubsub.asyncIterator(['NEW_MESSAGE']),
    },
  },
};
const server = createServer({ typeDefs, resolvers });
server.start(() => console.log('Server is running on http://localhost:4000'));
setInterval(() => {
  pubsub.publish('NEW_MESSAGE', { newMessage: 'Hello, world!' });
}, 1000);

File Uploads

This code sets up a GraphQL server that supports file uploads. It defines a custom scalar 'Upload' and a mutation 'singleUpload' that handles the file upload process.

const { createServer } = require('graphql-yoga');
const typeDefs = `
  scalar Upload
  type Query {
    hello: String!
  }
  type Mutation {
    singleUpload(file: Upload!): String!
  }
`;
const resolvers = {
  Query: {
    hello: () => 'Hello, world!',
  },
  Mutation: {
    singleUpload: async (parent, { file }) => {
      const { createReadStream, filename } = await file;
      createReadStream().pipe(fs.createWriteStream(path.join(__dirname, filename)));
      return filename;
    },
  },
};
const server = createServer({ typeDefs, resolvers });
server.start(() => console.log('Server is running on http://localhost:4000'));

Other packages similar to graphql-yoga

apollo-server

Apollo Server is a community-driven, open-source GraphQL server that works with any GraphQL schema. It provides a robust set of features, including caching, subscriptions, and more. Compared to graphql-yoga, Apollo Server offers more advanced features and integrations but may require more configuration.

express-graphql

express-graphql is a minimalistic GraphQL HTTP server middleware for Express. It is easy to set up and use, making it a good choice for simple applications. However, it lacks some of the advanced features provided by graphql-yoga, such as built-in subscriptions and file uploads.

graphql-koa

graphql-koa is a GraphQL server middleware for Koa. It provides a simple way to integrate GraphQL into a Koa application. While it is similar to express-graphql in terms of simplicity, it does not offer the same level of built-in features as graphql-yoga.

README

graphql-yoga

Fully-featured GraphQL Server with focus on easy setup, performance & great developer experience

Overview

• Easiest way to run a GraphQL server: Good defaults & includes everything you need with minimal setup.
• Includes Subscriptions: Built-in support for GraphQL Subscriptions using WebSockets.
• Compatible: Works with all GraphQL clients (Apollo, Relay...) and fits seamless in your GraphQL workflow.

graphql-yoga is based on the following libraries & tools:

• express/apollo-server: Performant, extensible web server framework
• graphql-subscriptions/subscriptions-transport-ws: GraphQL subscriptions server
• graphql.js/graphql-tools: GraphQL engine & schema helpers
• graphql-playground: Interactive GraphQL IDE

Features

• GraphQL spec-compliant
• File upload
• GraphQL Subscriptions
• TypeScript typings
• GraphQL Playground
• Extensible via Express middlewares
• Apollo Tracing
• Accepts both application/json and application/graphql content-type

Install

yarn add graphql-yoga

Usage

Quickstart (Hosted demo)

import { GraphQLServer } from 'graphql-yoga'
// ... or using `require()`
// const { GraphQLServer } = require('graphql-yoga')

const typeDefs = `
  type Query {
    hello(name: String): String!
  }
`

const resolvers = {
  Query: {
    hello: (_, { name }) => `Hello ${name || 'World'}`,
  },
}

const server = new GraphQLServer({ typeDefs, resolvers })
server.start(() => console.log('Server is running on localhost:4000'))

To get started with graphql-yoga, follow the instructions in the READMEs of the examples.

API

GraphQLServer

constructor(props: Props): GraphQLServer

The props argument accepts the following fields:

Key	Type	Default	Note
typeDefs	String	null	Contains GraphQL type definitions in SDL or file path to type definitions (required if schema is not provided *)
resolvers	Object	null	Contains resolvers for the fields specified in typeDefs (required if schema is not provided *)
schema	Object	null	An instance of GraphQLSchema (required if typeDefs and resolvers are not provided *)
context	Object	{}	Contains custom data being passed through your resolver chain
options	Object	{}	See below

(*) There are two major ways of providing the schema information to the constructor:

1. Provide typeDefs and resolvers and omit the schema, in this case graphql-yoga will construct the GraphQLSchema instance using makeExecutableSchema from graphql-tools.
2. Provide the schema directly and omit typeDefs and resolvers.

The options object has the following fields:

Key	Type	Default	Note
cors	Object	null	Contains configuration options for cors
disableSubscriptions	Boolean	false	Indicates whether subscriptions should be en- or disabled for your server
tracing	Boolean or String	false	Indicates whether Apollo Tracing should be en- or disabled for your server (if a string is provided, accepted values are: 'enabled', 'disabled', 'http-header')
port	Number	4000	Determines the port your server will be listening on (note that you can also specify the port by setting the PORT environment variable)
endpoint	String	'/'	Defines the HTTP endpoint of your server
subscriptionsEndpoint	String	'/'	Defines the subscriptions (websocket) endpoint for your server
playgroundEndpoint	String	'/'	Defines the endpoint where you can invoke the Playground
disablePlayground	Boolean	false	Indicates whether the Playground should be enabled
uploads	Object	null	Provides information about upload limits; the object can have any combination of the following three keys: maxFieldSize, maxFileSize, maxFiles; each of these have values of type Number

Here is example of creating a new server:

const options = {
  disableSubscriptions: false,  // same as default value
  port: 8000,
  endpoint: '/graphql',
  subscriptionsEndpoint: '/subscriptions',
  playgroundEndpoint: '/playground',
  disablePlayground: false      // same as default value
}

const typeDefs = `
  type Query {
    hello(name: String): String!
  }
`

const resolvers = {
  Query: {
    hello: (_, { name }) => `Hello ${name || 'World'}`,
  },
}

const server = new GraphQLServer({ typeDefs, resolvers, options })

start(callback: (() => void) = (() => null)): Promise<void>

Once your GraphQLServer is instantiated, you can call the start method on it. It takes one argument callback, a function that's invoked right before the server is started. As an example, the callback can be used to print information that the server was now started:

server.start(() => console.log(`Server started, listening on port 8000 for incoming requests.`))

PubSub

See the original documentation in graphql-subscriptions.

Endpoints

Examples

There are three examples demonstrating how to quickly get started with graphql-yoga:

• hello-world: Basic setup for building a schema and allowing for a hello query.
• subscriptions: Basic setup for using subscriptions with a counter that increments every 2 seconds and triggers a subscriptions.
• fullstack: Fullstack example based on create-react-app demonstrating how to query data from graphql-yoga with Apollo Client 2.0.

Workflow

Once your graphql-yoga server is running, you can use GraphQL Playground out of the box – typically running on localhost:4000. (Read here for more information.)

Deployment

now

To deploy your graphql-yoga server with now, follow these instructions:

1. Download Now Desktop
2. Navigate to the root directory of your graphql-yoga server
3. Run now in your terminal

Heroku

To deploy your graphql-yoga server with Heroku, follow these instructions:

1. Download and install the Heroku Command Line Interface (previously Heroku Toolbelt)
2. Log In to the Heroku CLI with heroku login
3. Navigate to the root directory of your graphql-yoga server
4. Create the Heroku instance by executing heroku create
5. Deploy your GraphQL server by executing git push heroku master

up (Coming soon 🔜 )

AWS Lambda (Coming soon 🔜 )

FAQ

How does graphql-yoga compare to apollo-server and other tools?

As mentioned above, graphql-yoga is built on top of a variety of other packages, such as graphql.js, express and apollo-server. Each of these provide a certain piece of functionality required for building a GraphQL server.

Using these packages individually incurs overhead in the setup process and requires you to write a lot of boilerplate. graphql-yoga abstracts away the initial complexity and required boilerplate and let's you get started quickly with a set of sensible defaults for your server configuration.

graphql-yoga is like create-react-app for building GraphQL servers.

Can't I just setup my own GraphQL server using express and graphql.js?

graphql-yoga is all about convenience and a great "Getting Started"-experience by abstracting away the complexity that comes when you're building your own GraphQL from scratch. It's a pragmatic approach to bootstrap a GraphQL server, much like create-react-app removes friction when first starting out with React.

Whenever the defaults of graphql-yoga are too tight of a corset for you, you can simply eject from it and use the tooling it's build upon - there's no lock-in or any other kind of magic going on preventing you from this.

How to eject from the standard express setup?

The core value of graphql-yoga is that you don't have to write the boilerplate required to configure your express.js application. However, once you need to add more customized behaviour to your server, the default configuration provided by graphql-yoga might not suit your use case any more. For example, it might be the case that you want to add more custom middleware to your server, like for logging or error reporting.

For these cases, GraphQLServer exposes the express.Application directly via its express property:

server.express.use(myMiddleware())

Middlewares can also be added specifically to the GraphQL endpoint route, by using:

server.express.post(server.options.endpoint, myMiddleware())

Any middlewares you add to that route, will be added right before the apollo-server-express middleware.

Help & Community

Join our Slack community if you run into issues or have questions. We love talking to you!