{"id":47948,"library":"graphql-subscriptions","title":"graphql-subscriptions","description":"GraphQL subscriptions is the official Apollo library for adding real-time capabilities to any GraphQL server via a PubSub pattern. Version 3.0.0 is stable, actively maintained, and ships TypeScript types. It works with any GraphQL.js-compatible server and client (not just Apollo). The package provides a lightweight PubSub implementation (EventEmitter-based for demos) and a `withFilter` helper for per-subscriber filtering. For production, you must swap the default PubSub for a store-backed implementation (e.g., Redis). It requires `graphql` ^15.7.2 or ^16 as a peer dependency and `es2018.asynciterable` in TypeScript configuration.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/apollographql/graphql-subscriptions","tags":["javascript","typescript"],"install":[{"cmd":"npm install graphql-subscriptions","lang":"bash","label":"npm"},{"cmd":"yarn add graphql-subscriptions","lang":"bash","label":"yarn"},{"cmd":"pnpm add graphql-subscriptions","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for GraphQL schema and resolver types.","package":"graphql","optional":false}],"imports":[{"note":"Named export, not default. Use named import for both JavaScript and TypeScript.","wrong":"import PubSub from 'graphql-subscriptions'","symbol":"PubSub","correct":"import { PubSub } from 'graphql-subscriptions'"},{"note":"If using CommonJS, require is acceptable but ESM is preferred. In TypeScript, named import is correct.","wrong":"const { withFilter } = require('graphql-subscriptions')","symbol":"withFilter","correct":"import { withFilter } from 'graphql-subscriptions'"},{"note":"Although a type, it can be imported as a value for interface checks. Type-only import is also valid in TS with `import type`.","wrong":"import type { PubSubEngine } from 'graphql-subscriptions'","symbol":"PubSubEngine","correct":"import { PubSubEngine } from 'graphql-subscriptions'"}],"quickstart":{"code":"import { PubSub, withFilter } from 'graphql-subscriptions';\n\nconst pubsub = new PubSub();\n\nconst SOMETHING_CHANGED_TOPIC = 'something_changed';\n\n// In your resolver map:\nconst resolvers = {\n  Subscription: {\n    somethingChanged: {\n      subscribe: withFilter(\n        () => pubsub.asyncIterableIterator(SOMETHING_CHANGED_TOPIC),\n        (payload, variables) => {\n          // Only push an event if the condition is met\n          return payload.somethingChanged.id === variables.id || !variables.id;\n        },\n      ),\n    },\n  },\n};\n\n// To publish an event:\npubsub.publish(SOMETHING_CHANGED_TOPIC, {\n  somethingChanged: { id: '123' },\n});","lang":"typescript","description":"Shows how to create a PubSub instance, define a subscription resolver with withFilter, and publish an event. Default PubSub is for demo only; replace for production."},"warnings":[{"fix":"Use a production-grade PubSub implementation like graphql-redis-subscriptions or graphql-mqtt-subscriptions.","message":"Default PubSub uses EventEmitter and does not work across multiple server instances or processes.","severity":"gotcha","affected_versions":">=2.0.0 <4"},{"fix":"Replace pubsub.subscribe(callback) with pubsub.asyncIterableIterator('TOPIC') in your subscribe resolver.","message":"In v3, PubSub no longer supports callback-based subscribe; use asyncIterableIterator.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"You can continue using withFilter, but for scalability, implement custom async iterators.","message":"The withFilter function is still supported but consider using a dedicated filtering library for complex logic.","severity":"deprecated","affected_versions":">=3.0.0"},{"fix":"Add 'es2018.asynciterable' to the 'lib' array in tsconfig.json.","message":"TypeScript users must have 'es2018.asynciterable' in tsconfig.json lib, otherwise they get TS errors.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Ensure the published object includes the key matching the subscription field name (e.g., { somethingChanged: { id: '123' } }).","message":"When using pubsub.publish, the payload must match the structure expected by the subscription resolver; otherwise, clients won't receive data.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"search_vec":"'15.7.2':87 '16':89 '3.0.0':26 'activ':29 'ad':12 'apollo':9,46 'back':80 'base':56 'capabl':16 'client':43 'compat':40 'configur':98 'default':74 'demo':58 'depend':93 'e.g':82 'es2018.asynciterable':95 'eventemitt':55 'eventemitter-bas':54 'filter':67 'graphql':2,4,19,86 'graphql-subscript':1 'graphql.js':39 'helper':62 'implement':53,81 'javascript':99 'librari':10 'lightweight':51 'maintain':30 'must':71 'offici':8 'packag':48 'pattern':24 'peer':92 'per':65 'per-subscrib':64 'product':69 'provid':49 'pubsub':23,52,75 'real':14 'real-tim':13 'redi':83 'requir':85 'server':20,41 'ship':32 'stabl':28 'store':79 'store-back':78 'subscrib':66 'subscript':3,5 'swap':72 'time':15 'type':34 'typescript':33,97,100 'version':25 'via':21 'withfilt':61 'work':36","created_at":"2026-06-07T16:54:09.079752+00:00","updated_at":"2026-06-07T16:54:09.079752+00:00","problems":[{"fix":"Replace `.asyncIterator()` with `.asyncIterableIterator()`.","cause":"In v3, the method was renamed from asyncIterator to asyncIterableIterator.","error":"TypeError: pubsub.asyncIterator is not a function"},{"fix":"Ensure graphql is version ^15.7.2 or ^16.0.0.","cause":"Incompatible graphql peer dependency version.","error":"Cannot use GraphQLSchema \"[object Object]\" with older version of graphql"},{"fix":"Return `pubsub.asyncIterableIterator(topic)` as the subscribe method.","cause":"The subscribe function did not return an AsyncIterable.","error":"Subscriptions only work with an AsyncIterable"},{"fix":"Use:\n  Subscription: {\n    somethingChanged: {\n      subscribe: () => pubsub.asyncIterableIterator(SOMETHING_CHANGED_TOPIC),\n    },\n  }","cause":"Returning a plain value instead of an object with a subscribe method.","error":"Expected subscription resolver to return an AsyncIterator"}],"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/apollographql/graphql-subscriptions#readme","github":"https://github.com/apollographql/graphql-subscriptions","docs":null,"changelog":null,"pypi":null,"npm":"graphql-subscriptions","openapi_spec":null,"status_page":null,"smithery":null,"categories":["api-integration"],"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}}