{"id":47979,"library":"graphql-workers-subscriptions","title":"graphql-workers-subscriptions","description":"A library for adding topic-based GraphQL subscriptions to Cloudflare Workers using Durable Objects and D1. Version 0.1.6 is the current stable release, with no mention of regular release cadence. Key differentiators include easy integration with existing GraphQL stacks (e.g., graphql-yoga, Apollo), in-database JSON filtering, and built-in authentication support for WebSocket connections. It leverages Cloudflare's Durable Objects for managing WebSocket connections and D1 for persisting subscription data, making it suitable for serverless environments with limited state.","status":"active","version":"0.1.6","language":"javascript","source_language":"en","source_url":"https://github.com/bubblydoo/graphql-workers-subscriptions","tags":["javascript","cloudflare","graphql","graphql-subscriptions","cloudflare-worker","graphql-ws","websocket","subscriptions","durable-objects","typescript"],"install":[{"cmd":"npm install graphql-workers-subscriptions","lang":"bash","label":"npm"},{"cmd":"yarn add graphql-workers-subscriptions","lang":"bash","label":"yarn"},{"cmd":"pnpm add graphql-workers-subscriptions","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Recommended for creating a GraphQL server with WebSocket support","package":"graphql-yoga","optional":true},{"reason":"Used to create executable schemas","package":"@graphql-tools/schema","optional":true},{"reason":"Used by graphql-yoga for WebSocket subscriptions","package":"graphql-ws","optional":true}],"imports":[{"note":"ESM-only library; CommonJS require will fail because the library is distributed as ESM modules.","wrong":"const { handleSubscriptions } = require('graphql-workers-subscriptions')","symbol":"handleSubscriptions","correct":"import { handleSubscriptions } from 'graphql-workers-subscriptions'"},{"note":"The correct import path is the main package, not a subpath. Typings are included.","wrong":"import { createWsConnectionPoolClass } from 'graphql-workers-subscriptions/methods'","symbol":"createWsConnectionPoolClass","correct":"import { createWsConnectionPoolClass } from 'graphql-workers-subscriptions'"},{"note":"Used as a resolver factory for subscription fields. The subscribe function is a named export.","wrong":"","symbol":"subscribe","correct":"import { subscribe } from 'graphql-workers-subscriptions'"},{"note":"This is a type export; can be used with 'import type' for TypeScript.","wrong":"import type { DefaultPublishableContext } from 'graphql-workers-subscriptions'","symbol":"DefaultPublishableContext","correct":"import { DefaultPublishableContext } from 'graphql-workers-subscriptions'"}],"quickstart":{"code":"import { makeExecutableSchema } from \"@graphql-tools/schema\";\nimport { createYoga } from \"graphql-yoga\";\nimport {\n  handleSubscriptions,\n  createWsConnectionPoolClass,\n  subscribe,\n  DefaultPublishableContext,\n  createDefaultPublishableContext,\n} from \"graphql-workers-subscriptions\";\n\nconst schema = makeExecutableSchema<DefaultPublishableContext<ENV>>({\n  typeDefs: `\n    type Query { ping: String }\n    type Subscription { greetings(greeting: String): Greeting }\n    type Mutation { greet(greeting: String!): String }\n    type Greeting { greeting: String }\n  `,\n  resolvers: {\n    Query: { ping: () => \"pong\" },\n    Mutation: {\n      greet: async (root, args, context) => {\n        context.publish(\"GREETINGS\", { greetings: { greeting: args.greeting } });\n        return \"ok\";\n      },\n    },\n    Subscription: {\n      greetings: {\n        subscribe: subscribe(\"GREETINGS\", {\n          filter: (root, args) => (args.greeting ? { greetings: { greeting: args.greeting } } : {}),\n        }),\n      },\n    },\n  },\n});\n\nconst settings = {\n  schema,\n  wsConnectionPool: (env: ENV) => env.WS_CONNECTION_POOL,\n  subscriptionsDb: (env: ENV) => env.SUBSCRIPTIONS,\n};\n\nconst yoga = createYoga<DefaultPublishableContext<ENV>>({ schema, graphiql: { subscriptionsProtocol: \"WS\" } });\n\nconst baseFetch: ExportedHandlerFetchHandler<ENV> = (request, env, executionCtx) =>\n  yoga.handleRequest(request, createDefaultPublishableContext({ env, executionCtx, ...settings }));\n\nconst fetch = handleSubscriptions({ fetch: baseFetch, ...settings });\n\nexport default { fetch };\nexport const WsConnectionPool = createWsConnectionPoolClass(settings);","lang":"typescript","description":"Sets up a Cloudflare Workers GraphQL endpoint with subscriptions using Durable Objects and D1."},"warnings":[{"fix":"Run 'wrangler d1 create SUBSCRIPTIONS --local' and 'wrangler d1 migrations apply SUBSCRIPTIONS --local' before 'wrangler dev'.","message":"WebSocket connections in development must use wrangler dev --local with D1 and Durable Objects properly configured.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure the filter returns an object with a key matching the subscription field name (e.g., { greetings: { greeting: args.greeting } }).","message":"The subscribe function's filter must return an object matching the subscription field's shape, or subscription may not work as expected.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Pin to a specific version and watch the repository for updates.","message":"This library is in early stages; APIs may change without major version bumps.","severity":"deprecated","affected_versions":"0.1.x"},{"fix":"Add [[d1_databases]] binding with name = 'SUBSCRIPTIONS' as shown in the README.","message":"D1 database bindings must be defined in wrangler.toml with the correct binding name 'SUBSCRIPTIONS'.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"search_vec":"'0.1.6':23 'ad':8 'apollo':49 'authent':59 'base':11 'built':57 'built-in':56 'cadenc':35 'cloudflar':15,66,90,96 'cloudflare-work':95 'connect':63,73 'current':26 'd1':21,75 'data':79 'databas':52 'differenti':37 'durabl':18,68,104 'durable-object':103 'e.g':45 'easi':39 'environ':85 'exist':42 'filter':54 'graphql':2,12,43,47,91,93,99 'graphql-subscript':92 'graphql-w':98 'graphql-workers-subscript':1 'graphql-yoga':46 'in-databas':50 'includ':38 'integr':40 'javascript':89 'json':53 'key':36 'leverag':65 'librari':6 'limit':87 'make':80 'manag':71 'mention':31 'object':19,69,105 'persist':77 'regular':33 'releas':28,34 'serverless':84 'stabl':27 'stack':44 'state':88 'subscript':4,13,78,94,102 'suitabl':82 'support':60 'topic':10 'topic-bas':9 'typescript':106 'use':17 'version':22 'websocket':62,72,101 'worker':3,16,97 'ws':100 'yoga':48","created_at":"2026-06-07T16:54:18.366188+00:00","updated_at":"2026-06-07T16:54:18.366188+00:00","problems":[{"fix":"Run 'npm install graphql-workers-subscriptions' and ensure import is from 'graphql-workers-subscriptions'.","cause":"The package is not installed or the import path is wrong.","error":"Error: Cannot find module 'graphql-workers-subscriptions'"},{"fix":"Ensure graphql-yoga is version 3.x and that you are using 'createYoga' correctly.","cause":"graphql-yoga version mismatch or incorrect initialization.","error":"TypeError: yoga.handleRequest is not a function"},{"fix":"Run 'wrangler d1 create SUBSCRIPTIONS' and verify the binding name in wrangler.toml matches 'SUBSCRIPTIONS'.","cause":"The D1 database has not been created or the binding name is incorrect.","error":"D1 database 'SUBSCRIPTIONS' not found"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/bubblydoo/graphql-workers-subscriptions#readme","github":"https://github.com/bubblydoo/graphql-workers-subscriptions","docs":null,"changelog":null,"pypi":null,"npm":"graphql-workers-subscriptions","openapi_spec":null,"status_page":null,"smithery":null,"categories":["messaging"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}