diff --git a/README.md b/README.md index f548cc2..d51db39 100644 --- a/README.md +++ b/README.md @@ -26,14 +26,55 @@ const graphQLOptions = { 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](https://workers.dev) subdomain, the default of `false` is fine). -Finally, while configuring your server, you may want to set the `debug` flag to `true`, to allow script errors to be returned in your browser. This can be useful for debugging any errors while setting up your GraphQL server. +### 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: + +```js +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`](https://www.apollographql.com/docs/apollo-server/features/data-sources/), using KV. To use caching in your project, [create a new KV namespace](https://workers.cloudflare.com/docs/reference/storage/writing-data), and in `wrangler.toml`, configure your namespace, calling it `WORKERS_GRAPHQL_CACHE`: + +```toml +# 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