{"id":13402224,"url":"https://github.com/cloudflare/workers-graphql-server","last_synced_at":"2025-05-14T19:09:06.108Z","repository":{"id":37456590,"uuid":"184490547","full_name":"cloudflare/workers-graphql-server","owner":"cloudflare","description":"🔥Lightning-fast, globally distributed Apollo GraphQL server, deployed at the edge using Cloudflare Workers","archived":false,"fork":false,"pushed_at":"2024-12-06T02:19:45.000Z","size":844,"stargazers_count":747,"open_issues_count":1,"forks_count":592,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-04-13T15:07:42.468Z","etag":null,"topics":["apollo","cloudflare-workers","graphql","serverless"],"latest_commit_sha":null,"homepage":"https://graphql-on-workers.signalnerve.com/___graphql","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloudflare.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-05-01T22:37:07.000Z","updated_at":"2025-04-12T23:03:27.000Z","dependencies_parsed_at":"2024-10-03T21:41:00.854Z","dependency_job_id":"655ae7a7-2895-44db-8042-5e822f8745ac","html_url":"https://github.com/cloudflare/workers-graphql-server","commit_stats":null,"previous_names":["signalnerve/workers-graphql-server"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fworkers-graphql-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fworkers-graphql-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fworkers-graphql-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fworkers-graphql-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloudflare","download_url":"https://codeload.github.com/cloudflare/workers-graphql-server/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254209859,"owners_count":22032897,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apollo","cloudflare-workers","graphql","serverless"],"created_at":"2024-07-30T19:01:13.162Z","updated_at":"2025-05-14T19:09:04.529Z","avatar_url":"https://github.com/cloudflare.png","language":"TypeScript","readme":"# workers-graphql-server\n\nAn [Apollo GraphQL](https://www.apollographql.com/) server, built with [Cloudflare Workers](https://workers.cloudflare.com).\n\nWhether you host your APIs on-prem, in the cloud, or you're deploying [databases](https://developers.cloudflare.com/d1) to Cloudflare directly, you can deploy a globally distributed GraphQL server with Cloudflare Workers.\n\n## Setup\n\nBegin by cloning this repo and installing the dependencies:\n\n```sh\n$ git clone https://github.com/cloudflare/workers-graphql-server\n$ npm install\n```\n\nYou can begin running the project locally by running `npm run dev`.\n\nYou'll need to configure your project's `wrangler.toml` file to prepare your project for deployment. See the [\"Configuration\"](https://developers.cloudflare.com/workers/cli-wrangler/configuration/) docs for a guide on how to do this.\n\n## Usage\n\nThe source for this project shows how to make requests to external APIs, using the [PokeAPI](https://pokeapi.co/) as an example. You can run an example query to ensure it works after deployment:\n\n```graphql\nquery {\n  pokemon: pokemon(id: 1) {\n    id\n    name\n    height\n    weight\n    sprites {\n      front_shiny\n      back_shiny\n    }\n  }\n}\n```\n\nResolvers are defined in `src/resolvers.ts`. You can also use [Service Bindings](https://developers.cloudflare.com/workers/runtime-apis/bindings/service-bindings/) to connect to other Workers services, and use them inside your resolvers.\n\nIf you change your GraphQL schema at `src/schema.graphql`, you'll need to run `npm run codegen` to update the generated types in `src/generated/graphql.ts`. This ensures that you can correctly import and type your resolvers.\n\n## Configuration\n\nYou can optionally configure your `graphQLOptions` object in `src/index.js`:\n\n```js\nconst graphQLOptions = {\n  baseEndpoint: '/',\n  enableSandbox: true,\n  forwardUnmatchedRequestsToOrigin: false,\n  cors: true,\n  kvCache: false,\n}\n```\n\n### Base endpoint\n\nMake requests to your GraphQL server by sending `POST` requests to the `baseEndpoint` (e.g. `graphql-on-workers.signalnerve.com/`).\n\n### Sandbox\n\nBy default, the Apollo Sandbox is enabled. This allows you to test your GraphQL in a web GUI without needing to write any client code.\n\n### Origin forwarding\n\nIf 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).\n\n### Debugging\n\nWhile 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.\n\n### CORS\n\nBy 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. This is done by passing an object to `cors`, which is based on the [hono/cors](https://hono.dev/docs/middleware/builtin/cors) middleware:\n\n```js\nconst graphQLOptions = {\n  // ... other options ...\n\n  cors: {\n    origin: 'http://example.com',\n    allowHeaders: ['X-Custom-Header', 'Upgrade-Insecure-Requests'],\n    allowMethods: ['POST', 'GET', 'OPTIONS'],\n    exposeHeaders: ['Content-Length', 'X-Kuma-Revision'],\n    maxAge: 600,\n    credentials: true,\n  },\n}\n```\n\n### Caching\n\nThis project includes support for using Workers KV as a cache in your resolvers. 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 `KV_CACHE` (note that this binding name is _required_, currently):\n\n```toml\n# wrangler.toml\n\n[[kv-namespaces]]\nbinding = \"KV_CACHE\"\nid = \"$myId\"\n```\n\nWith 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`.\n\nIn any resolver function, you can access the `cache` object, which is an instance of [`KVCache`](https://github.com/cloudflare/workers-graphql-server/blob/master/src/kv-cache.ts). You can use `.get` and `.set` to interact with the cache:\n\n```ts\npokemon: async (_parent, { id }, { cache }) =\u003e {\n  if (cache) {\n    const pokemon = await cache.get(id)\n    if (pokemon) {\n      return pokemon\n    }\n  }\n\n  // You can hook into any util functions, API wrappers, or other\n  // code that you need to resolve your query.\n  const pokemonData = await PokemonAPI.getPokemon(id)\n\n  // You can also cache the data if you need to, with an optional TTL\n  if (cache) await cache.set(id, pokemonData, { ttl: 60 })\n  return pokemonData\n},\n```\n\n## Credits\n\nThis project is heavily based on the [@as-integrations/cloudflare-workers](https://github.com/apollo-server-integrations/apollo-server-integration-cloudflare-workers) package, which is a great tool for building GraphQL servers with Cloudflare Workers.\n\nIt is built with [Hono](https://github.com/honojs/hono), a simple and powerful web framework for Cloudflare Workers.\n\n## License\n\nThis project is licensed with the [MIT License](https://github.com/cloudflare/workers-graphql-server/blob/master/LICENSE).\n","funding_links":[],"categories":["TypeScript","JavaScript","Frameworks \u0026 Libraries"],"sub_categories":["Web Frameworks"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudflare%2Fworkers-graphql-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloudflare%2Fworkers-graphql-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudflare%2Fworkers-graphql-server/lists"}