README.md

workers-graphql-server

An Apollo GraphQL server, built with Cloudflare Workers. Try a demo by looking at a deployed GraphQL playground.

Why this rules: Cloudflare Workers is a serverless application platform for deploying your projects across Cloudflare's massive distributed network. Deploying your GraphQL application to the edge is a huge opportunity to build consistent low-latency API servers, with the added benefits of "serverless" (I know, the project has server in it): usage-based pricing, no cold starts, and instant, easy-to-use deployment software, using Wrangler.

By the way - as a full-stack developer who loves GraphQL, and the developer advocate for Cloudflare Workers, I would love to see what you build with this! Let me know on Twitter!

Usage

You can begin building your own Workers GraphQL server by installing Wrangler, the Workers command-line tool, and generating a new project:

wrangler generate my-graphql-server https://github.com/cloudflare/workers-graphql-server

You'll need to configure your project's wrangler.toml file to prepare your project for deployment. See the "Configuration" docs for a guide on how to do this. Note that you'll need to find your Cloudflare API keys to set up your config file.

The source for this project includes an example external REST data source, and defined types for the PokeAPI, as an example of how to integrate external APIs. Once you have the worker available, try this query as a sanity check:

query samplePokeAPIquery {
  pokemon: pokemon(id:1) {
    id,
    name,
    height,
    weight,
    sprites{
      front_shiny,
      back_shiny
    }
  }
}

To start using the project, configure your graphQLOptions object in src/index.js:

const graphQLOptions = {
  baseEndpoint: '/', // String
  playgroundEndpoint: '/___graphql', // ?String
  forwardUnmatchedRequestsToOrigin: false, // Boolean
  debug: false, // Boolean
  cors: true, // Boolean or Object to further configure
  kvCache: false, // Boolean
}

Endpoints

Make requests to your GraphQL server at the baseEndpoint (e.g. graphql-on-workers.signalnerve.com/) and, if configured, try GraphQL queries at the playgroundEndpoint (e.g. graphql-on-workers.signalnerve.com/___graphql).

Origin forwarding

If you run your GraphQL server on a domain already registered with Cloudflare, you may want to pass any unmatched requests from inside your Workers script to your origin: in that case, set forwardUnmatchedRequestToOrigin to true (if you're running a GraphQL server on a Workers.dev subdomain, the default of false is fine).

Debugging

While configuring your server, you may want to set the debug flag to true, to return script errors in your browser. This can be useful for debugging any errors while setting up your GraphQL server, but should be disabled on a production server.

CORS

By default, the cors option allows cross-origin requests to the server from any origin. You may wish to configure it to whitelist specific origins, methods, or headers. To do this, change the cors option to an object:

const graphQLOptions = {
  // ... other options ...

  cors: {
    allowCredentials: 'true',
    allowHeaders: 'Content-type',
    allowOrigin: '*',
    allowMethods: 'GET, POST, PUT',
  },
}

Note that by default, any field that you don't pass here (e.g. allowMethods) will fallback to the default value. See utils/setCors.js for the default values for these fields.

REST caching

Version 1.1.0 of this project includes support for caching external requests made via instances of RESTDataSource, using KV. To use caching in your project, create a new KV namespace, and in wrangler.toml, configure your namespace, calling it WORKERS_GRAPHQL_CACHE:

# wrangler.toml

[[kv-namespaces]]
binding = "WORKERS_GRAPHQL_CACHE"
id = "$myId"

With a configured KV namespace set up, you can opt-in to KV caching by changing the kvCache config value in graphQLOptions (in index.js) to true.

License

This project is licensed with the MIT License.