https://github.com/o-az/workers-graphql
Fast, globally distributed GraphQL Server 🌐 - deployed at the edge using Cloudflare Workers 🔶
https://github.com/o-az/workers-graphql
cloudflare-workers graphql graphql-yoga hono
Last synced: about 2 months ago
JSON representation
Fast, globally distributed GraphQL Server 🌐 - deployed at the edge using Cloudflare Workers 🔶
- Host: GitHub
- URL: https://github.com/o-az/workers-graphql
- Owner: o-az
- Created: 2024-10-27T07:44:22.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2024-11-24T01:44:05.000Z (11 months ago)
- Last Synced: 2025-04-01T14:37:43.015Z (6 months ago)
- Topics: cloudflare-workers, graphql, graphql-yoga, hono
- Language: TypeScript
- Homepage: https://workers-graphql.evm.workers.dev/graphql
- Size: 319 KB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
GraphQL on Cloudflare Workers
> Fast 💨 ([hono benchmarks](https://hono.dev/docs/concepts/benchmarks) - [yoga benchmarks](https://github.com/ardatan/graphql-server-benchmarks/tree/federation#apollo-federation-server-benchmarks)), maximally extensible 🔗, globally distributed 🌐, deployed at the edge using Cloudflare Workers 🔶
| One Click Deploy | Instant Development |
| ---------------- | ------------------- |
| [](https://deploy.workers.cloudflare.com/?url=https://github.com/o-az/workers-graphql) | [](https://gitpod.io/#https://github.com/o-az/workers-graphql) |
[Hono](https://hono.dev) as a base router, [GraphQL Yoga](https://the-guild.dev/graphql/yoga-server/docs) server, runs on [Cloudflare Workers](https://developers.cloudflare.com/workers) runtime.
This stack is maximally extensible. To extend the GraphQL server functionalities, see [Envelop Plugins](https://the-guild.dev/graphql/envelop/plugins) – there's a plugin for everything you need. To extend Hono (the router), see the list of [middlewares](https://hono.dev/docs/middleware/third-party) – on the left side menu is the list of official middlewares and on the page itself is a list of community middlewares.
### Local Development
Clone the repo and install dependencies:
```bash
gh repo clone o-az/workers-graphql
cd workers-graphql
# if you don't have github cli `gh`, you should
# git clone https://github.com/o-az/workers-graphql
```
Install dependencies and start the development server:
```bash
pnpm install
pnpm dev
```
## Usage
examples on how to query, subscribe, access playground, introspect, see cache, etc.
### GraphiQL Playground
[workers-graphql.evm.workers.dev/graphiql](https://workers-graphql.evm.workers.dev/graphql)
### Query Request Examples
Usually GraphQL queries are sent as `POST` requests but here we can also send them as `GET` requests. We `encodeURIComponent` the query and add it to the URL as a query parameter. `GET` example:
```bash
curl --request GET \
--url 'https://workers-graphql.evm.workers.dev/graphql?query=%7B+health+%7D'
```
Classic `POST` example:
```bash
curl --request POST \
--url https://workers-graphql.evm.workers.dev/graphql \
--header 'content-type: application/json' \
--data '{ "query": "{ health }" }'
```
### Subscription Request Example
```graphql
subscription {
countdown(from: 3)
}
```
Notice the `Accept: text/event-stream` header.
```bash
# GET request
curl --request GET \
--header 'Accept: text/event-stream' \
--url 'https://workers-graphql.evm.workers.dev/graphql?query=subscription%7Bcountdown%28from%3A3%29%7D'
# output
# event: next
# data: {"data":{"countdown":3}}
# event: next
# data: {"data":{"countdown":2}}
# event: next
# data: {"data":{"countdown":1}}
# event: next
# data: {"data":{"countdown":0}}
# event: complete
```
### Introspection
`.graphql` schema:
```sh
pnpm dlx @graphql-inspector/cli \
introspect https://workers-graphql.evm.workers.dev/graphql \
--write schema.graphql
# or npx, or yarn dlx, or bunx
```
`.json` schema:
```sh
pnpm dlx @graphql-inspector/cli \
introspect https://workers-graphql.evm.workers.dev/graphql \
--write schema.json
# or npx, or yarn dlx, or bunx
```
You can also introspect with a `curl` request:
```bash
# assuming you have jq installed
curl --silent --location \
--request POST \
--url 'https://workers-graphql.evm.workers.dev/graphql' \
--header 'Content-Type: application/json' \
--data '{"query":"query IntrospectionQuery { __schema { description queryType { name description } mutationType { name description } subscriptionType { name description } types { ...FullType } directives { name description locations args { ...InputValue } } } } fragment FullType on __Type { kind name description fields(includeDeprecated: true) { name description args { ...InputValue } type { ...TypeRef } isDeprecated deprecationReason } inputFields { ...InputValue } interfaces { ...TypeRef } enumValues(includeDeprecated: true) { name description isDeprecated deprecationReason } possibleTypes { ...TypeRef } } fragment InputValue on __InputValue { name description type { ...TypeRef } defaultValue } fragment TypeRef on __Type { kind name description ofType { kind name description ofType { kind name description ofType { kind name description ofType { kind name description ofType { kind name description ofType { kind name description ofType { kind name description } } } } } } } }","variables":{}}' \
| jq '.data' > schema.json
```
### Response Caching Example
I manually set the resolver of this query to take 5 seconds for the first request.
Then subsequent requests will be served from the cache for the next n seconds.
To find out how long the cache is set to, search for `@cacheControl` in [./src/graphql.ts](./src/graphql.ts).
To try this, visit [workers-graphql.evm.workers.dev/graphql?query=%7B+slow+%7D](https://workers-graphql.evm.workers.dev/graphql?query=%7B+slow+%7D) in the browser.
Run the query, notice the slowness, and then run it again a few times to see the cache in action.