# graphql-yoga
**Repository Path**: william_ning/graphql-yoga
## Basic Information
- **Project Name**: graphql-yoga
- **Description**: 🧘 Fully-featured GraphQL Server with focus on easy setup, performance & great developer experience
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2021-03-12
- **Last Updated**: 2021-03-12
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# graphql-yoga
[](https://circleci.com/gh/prisma/graphql-yoga) [](https://badge.fury.io/js/graphql-yoga)
Fully-featured GraphQL Server with focus on easy setup, performance & great developer experience
## Overview
* **Easiest way to run a GraphQL server:** Sensible 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`](https://github.com/expressjs/express)/[`apollo-server`](https://github.com/apollographql/apollo-server): Performant, extensible web server framework
* [`graphql-subscriptions`](https://github.com/apollographql/graphql-subscriptions)/[`subscriptions-transport-ws`](https://github.com/apollographql/subscriptions-transport-ws): GraphQL subscriptions server
* [`graphql.js`](https://github.com/graphql/graphql-js)/[`graphql-tools`](https://github.com/apollographql/graphql-tools): GraphQL engine & schema helpers
* [`graphql-playground`](https://github.com/graphcool/graphql-playground): Interactive GraphQL IDE
## Features
* GraphQL spec-compliant
* File upload
* GraphQL Subscriptions
* TypeScript typings
* GraphQL Playground
* Extensible via Express middleware
* Schema directives
* Apollo Tracing
* Accepts both `application/json` and `application/graphql` content-types
* Runs everywhere: Can be deployed via `now`, `up`, AWS Lambda, Heroku etc.
* Supports middleware out of the box.
## Install
```sh
yarn add graphql-yoga
```
## Usage
### Quickstart ([Hosted demo](https://demo-graphql-yoga.glitch.me))
```ts
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](./examples).
### API
#### `GraphQLServer`
##### `constructor(props: Props): GraphQLServer`
The `props` argument accepts the following fields:
| Key | Type | Default | Note |
| --------------------------- | --------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `typeDefs` | `String` or `Function` or `DocumentNode` or `array` of previous | `null` | Contains GraphQL type definitions in [SDL](https://blog.graph.cool/graphql-sdl-schema-definition-language-6755bcb9ce51) 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 \*) |
| `resolverValidationOptions` | Object | `null` | Object which controls the resolver validation behaviour (see ["Generating a schema"](https://www.apollographql.com/docs/graphql-tools/generate-schema.html#makeExecutableSchema)) for more information |
| `schema` | Object | `null` | An instance of [`GraphQLSchema`](http://graphql.org/graphql-js/type/#graphqlschema) (required if `typeDefs` and `resolvers` are not provided \*) |
| `mocks` | Object or Boolean | `null` | Applies [mocks to schema](https://github.com/apollographql/graphql-tools/blob/master/docs/source/mocking.md). Setting this to true will apply a default mock, however you can pass an object to customize the mocks similar to the resolvers map. |
| `context` | Object or Function | `{}` | Contains custom data being passed through your resolver chain. This can be passed in as an object, or as a Function with the signature `(req: ContextParameters) => any` \*\* |
| `schemaDirectives` | Object | `null` | [`Apollo Server schema directives`](https://www.apollographql.com/docs/graphql-tools/schema-directives.html) that allow for transforming schema types, fields, and arguments |
| `middlewares` | `array` of Middleware | `[]` | A list of [`GraphQLMiddleware`](https://github.com/graphcool/graphql-middleware) middleware. |
> (\*) There are two major ways of providing the [schema](https://blog.graph.cool/graphql-server-basics-the-schema-ac5e2950214e) 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`](https://www.apollographql.com/docs/graphql-tools/generate-schema.html#makeExecutableSchema) from [`graphql-tools`](https://github.com/apollographql/graphql-tools).
> 2. Provide the `schema` directly and omit `typeDefs` and `resolvers`.
> (\*\*) Notice that the `req` argument is an object of the shape `{ request, response, connection }` which either carries a `request: Request` property (when it's a `Query`/`Mutation` resolver), `response: Response` property (when it's a `Query`/`Mutation` resolver), or a `connection: SubscriptionOptions` property (when it's a `Subscription` resolver). [`Request`](http://expressjs.com/en/api.html#req) is imported from Express.js. [`Response`](http://expressjs.com/en/api.html#res) is imported from Express.js aswell. `SubscriptionOptions` is from the [`graphql-subscriptions`](https://github.com/apollographql/graphql-subscriptions) package. `SubscriptionOptions` are getting the `connectionParams` automatically injected under `SubscriptionOptions.context.[CONNECTION_PARAMETER_NAME]`
Here is example of creating a new server:
```js
const typeDefs = `
type Query {
hello(name: String): String!
}
`
const resolvers = {
Query: {
hello: (_, { name }) => `Hello ${name || 'World'}`,
},
}
const server = new GraphQLServer({ typeDefs, resolvers })
```
#### `start(options: Options, callback: ((options: Options) => void) = (() => null)): Promise`
Once your `GraphQLServer` is instantiated, you can call the `start` method on it. It takes two arguments: `options`, the options object defined above, and `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 has started.
The `options` object has the following fields:
| Key | Type | Default | Note |
| ------------------------ | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cors` | Object | `null` | Contains [configuration options](https://github.com/expressjs/cors#configuration-options) for [cors](https://github.com/expressjs/cors) |
| `tracing` | Boolean or [TracingOptions](/src/types.ts#L49-L51) | `'http-header'` | Indicates whether [Apollo Tracing](https://github.com/apollographql/apollo-tracing) should be enabled or disabled for your server (if a string is provided, accepted values are: `'enabled'`, `'disabled'`, `'http-header'`) |
| `port` | Number or String | `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 |
| `subscriptions` | Object or String or `false` | `'/'` | Defines the subscriptions (websocket) endpoint for your server; accepts an object with [subscription server options](https://github.com/apollographql/subscriptions-transport-ws#constructoroptions-socketoptions) `path`, `keepAlive`, `onConnect` and `onDisconnect`; setting to `false` disables subscriptions completely |
| `playground` | String or `false` | `'/'` | Defines the endpoint where you can invoke the [Playground](https://github.com/graphcool/graphql-playground); setting to `false` disables the playground endpoint |
| `defaultPlaygroundQuery` | String | `undefined` | Defines default query displayed in Playground. |
| `uploads` | [UploadOptions](/src/types.ts#L39-L43) or `false` or `undefined` | `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; setting to `false` disables file uploading |
| `https` | [HttpsOptions](/src/types.ts#L62-L65) or `undefined` | `undefined` | Enables HTTPS support with a key/cert |
| `getEndpoint` | String or Boolean | `false` | Adds a graphql HTTP GET endpoint to your server (defaults to `endpoint` if `true`). Used for leveraging CDN level caching. |
| `deduplicator` | Boolean | `true` | Enables [graphql-deduplicator](https://github.com/gajus/graphql-deduplicator). Once enabled sending the header `X-GraphQL-Deduplicate` will deduplicate the data. |
| `bodyParserOptions` | BodyParserJSONOptions | [BodyParserJSONOptions Defaults](https://github.com/expressjs/body-parser#bodyparserjsonoptions) | Allows pass through of [body-parser options](https://github.com/expressjs/body-parser#bodyparserjsonoptions) |
Additionally, the `options` object exposes these `apollo-server` options:
| Key | Type | Note |
| ----------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `cacheControl` | Boolean | Enable extension that returns Cache Control data in the response |
| `formatError` | Number | A function to apply to every error before sending the response to clients. Defaults to [defaultErrorFormatter](https://github.com/graphcool/graphql-yoga/blob/master/src/defaultErrorFormatter.ts). Please beware, that if you override this, `requestId` and `code` on errors won't automatically be propagated to your yoga server |
| `logFunction` | LogFunction | A function called for logging events such as execution times |
| `rootValue` | any | RootValue passed to GraphQL execution |
| `validationRules` | Array of functions | Additional GraphQL validation rules to be applied to client-specified queries |
| `fieldResolver` | GraphQLFieldResolver | Specify a custom default field resolver function |
| `formatParams` | Function | A function applied to each query in a batch to format parameters before execution |
| `formatResponse` | Function | A function applied to each response after execution |
| `debug` | boolean | Print additional debug logging if execution errors occur |
```js
const options = {
port: 8000,
endpoint: '/graphql',
subscriptions: '/subscriptions',
playground: '/playground',
}
server.start(options, ({ port }) =>
console.log(
`Server started, listening on port ${port} for incoming requests.`,
),
)
```
#### `PubSub`
See the original documentation in [`graphql-subscriptions`](https://github.com/apollographql/graphql-subscriptions).
#### `mocking`
Mocking the schema is straight forward, along wit
```javascript
import { GraphqlServer, MockList } from 'graphql-yoga'
const typeDefs = `
type Query {
hello(name: String): String!
listOfStrings: [String]
}
`
const mocks = {
Query: () => ({
hello: () => 'Hello World',
listOfStrings: () => new MockList([2, 6]),
}),
}
const server = new GraphQLServer({ typeDefs, mocks })
```
### Endpoints
## Examples
There are three examples demonstrating how to quickly get started with `graphql-yoga`:
* [hello-world](./examples/hello-world): Basic setup for building a schema and allowing for a `hello` query.
* [subscriptions](./examples/subscriptions): Basic setup for using subscriptions with a counter that increments every 2 seconds and triggers a subscription.
* [fullstack](./examples/fullstack): Fullstack example based on [`create-react-app`](https://github.com/facebookincubator/create-react-app) demonstrating how to query data from `graphql-yoga` with [Apollo Client 2.0](https://www.apollographql.com/client/).
## Workflow
Once your `graphql-yoga` server is running, you can use [GraphQL Playground](https://github.com/graphcool/graphql-playground) out of the box – typically running on `localhost:4000`. (Read [here](https://blog.graph.cool/introducing-graphql-playground-f1e0a018f05d) for more information.)
[](https://www.graphqlbin.com/RVIn)
## Deployment
### `now`
To deploy your `graphql-yoga` server with [`now`](https://zeit.co/now), follow these instructions:
1. Download [**Now Desktop**](https://zeit.co/download)
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](https://heroku.com), follow these instructions:
1. Download and install the [Heroku Command Line Interface](https://devcenter.heroku.com/articles/heroku-cli#download-and-install) (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 provides 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 lets you get started quickly with a set of sensible defaults for your server configuration.
`graphql-yoga` is like [`create-react-app`](https://github.com/facebookincubator/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 server from scratch. It's a pragmatic approach to bootstrap a GraphQL server, much like how [`create-react-app`](https://github.com/facebookincubator/create-react-app) removes friction when first starting out with React.
Whenever the defaults of `graphql-yoga` are too tight a corset for you, you can simply _eject_ from it and use the tooling it's built upon - there's no lock-in or any other kind of magic going on preventing you from doing 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](https://github.com/expressjs/) 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`](./src/index.ts#L17) property:
```js
server.express.use(myMiddleware())
```
Middleware can also be added specifically to the GraphQL endpoint route, by using:
```js
server.express.post(server.options.endpoint, myMiddleware())
```
Any middleware you add to that route, will be added right before the `apollo-server-express` middleware.
## Help & Community [](https://slack.prisma.io)
Join our [Slack community](http://slack.graph.cool/) if you run into issues or have questions. We love talking to you!
