workers-graphql-server
workers-graphql-server copied to clipboard
ð¥Lightning-fast, globally distributed Apollo GraphQL server, deployed at the edge using Cloudflare Workers
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.