npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@eliperelman/graphql-yoga

v1.2.0

Published

<p align="center"><img src="https://imgur.com/Sv6j0B6.png" width="100" /></p>

Downloads

5

Readme

graphql-yoga

CircleCI npm version

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:

Features

  • GraphQL spec-compliant
  • File upload
  • GraphQL Subscriptions
  • TypeScript typings
  • GraphQL Playground
  • Extensible via Express middlewares
  • Apollo Tracing
  • Apollo Engine integration
  • Accepts both application/json and application/graphql content-type
  • Runs everywhere: Can be deployed via now, up, AWS Lambda, Heroku etc

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 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 ** |

(*) 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.

(**) Notice that the req argument is an object of the shape { request, connection } which either carries a request: Request property (in case it's a Query/Mutation resolver) or a connection: SubscriptionOptions property (in case it's a Subscription resolver). Request is imported from Express.js. SubscriptionOptions is from the graphql-subscriptions package. SubscriptionOptions are getting the connectionParams automatically injected under SubscriptionOptions.context.[CONNECTION_PARAMETER_NAME]

Here is example of creating a new server:

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<void>

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 was now started.

The options object has the following fields:

| Key | Type | Default | Note | | --- | --- | --- | --- | | cors | Object | null | Contains configuration options for cors | | tracing | Boolean or String | 'http-header' | 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 | | subscriptions | Object or String or false | '/' | Defines the subscriptions (websocket) endpoint for your server; accepts an object with subscription server options path, keepAlive, onConnect and onDisconnect; setting to false disables subscriptions completely | | playground | String or false | '/' | Defines the endpoint where you can invoke the Playground; setting to false disables the playground endpoint | | uploads | UploadOptions 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 | | apolloEngine | string or object | null | A string API key for Apollo Engine, or an object of Apollo Engine options, including apiKey, for proxying through Apollo Engine. You should also set tracing and cacheControl options accordingly. |

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 | | logFunction | LogFunction | A function called for logging events such as execution times | | rootValue | any | RootValue passed to GraphQL execution | | validationRules | Array of functions | DAdditional GraphQL validation rules to be applied to client-specified queries | | fieldResolver | GraphQLFieldResolver | Specifify a custom default field resolver function | formatParams | Function | A function applied for 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 |

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.

Endpoints

Examples

There are four 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.
  • apollo-engine: Basic setup for integrating with Apollo Engine.

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 Slack Status

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