Registry / api-integration / graphql-subscriptions

graphql-subscriptions

library3.0.0jsnpmunverified

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.

api-integration

npm install graphql-subscriptions

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRAPHQL-SUBSCRIPTI

graphql-subscriptions

api-integrationjavascriptv3.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

PubSub

✓ import { PubSub } from 'graphql-subscriptions'

✗ import PubSub from 'graphql-subscriptions'

Named export, not default. Use named import for both JavaScript and TypeScript.

withFilter

✓ import { withFilter } from 'graphql-subscriptions'

✗ const { withFilter } = require('graphql-subscriptions')

If using CommonJS, require is acceptable but ESM is preferred. In TypeScript, named import is correct.

PubSubEngine

✓ import { PubSubEngine } from 'graphql-subscriptions'

✗ import type { PubSubEngine } from 'graphql-subscriptions'

Although a type, it can be imported as a value for interface checks. Type-only import is also valid in TS with `import type`.

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.

import { PubSub, withFilter } from 'graphql-subscriptions'; const pubsub = new PubSub(); const SOMETHING_CHANGED_TOPIC = 'something_changed'; // In your resolver map: const resolvers = { Subscription: { somethingChanged: { subscribe: withFilter( () => pubsub.asyncIterableIterator(SOMETHING_CHANGED_TOPIC), (payload, variables) => { // Only push an event if the condition is met return payload.somethingChanged.id === variables.id || !variables.id; }, ), }, }, }; // To publish an event: pubsub.publish(SOMETHING_CHANGED_TOPIC, { somethingChanged: { id: '123' }, });

Debug

Known issues

gotchaDefault PubSub uses EventEmitter and does not work across multiple server instances or processes.

fix

Use a production-grade PubSub implementation like graphql-redis-subscriptions or graphql-mqtt-subscriptions.

affects: >=2.0.0 <4

breakingIn v3, PubSub no longer supports callback-based subscribe; use asyncIterableIterator.

fix

Replace pubsub.subscribe(callback) with pubsub.asyncIterableIterator('TOPIC') in your subscribe resolver.

affects: >=3.0.0

deprecatedThe withFilter function is still supported but consider using a dedicated filtering library for complex logic.

fix

You can continue using withFilter, but for scalability, implement custom async iterators.

affects: >=3.0.0

gotchaTypeScript users must have 'es2018.asynciterable' in tsconfig.json lib, otherwise they get TS errors.

fix

Add 'es2018.asynciterable' to the 'lib' array in tsconfig.json.

affects: >=2.0.0

gotchaWhen using pubsub.publish, the payload must match the structure expected by the subscription resolver; otherwise, clients won't receive data.

fix

Ensure the published object includes the key matching the subscription field name (e.g., { somethingChanged: { id: '123' } }).

affects: >=2.0.0

Errors

Common errors & fixes

TypeError: pubsub.asyncIterator is not a function

In v3, the method was renamed from asyncIterator to asyncIterableIterator.

fix

Replace `.asyncIterator()` with `.asyncIterableIterator()`.

Cannot use GraphQLSchema "[object Object]" with older version of graphql

Incompatible graphql peer dependency version.

fix

Ensure graphql is version ^15.7.2 or ^16.0.0.

Subscriptions only work with an AsyncIterable

The subscribe function did not return an AsyncIterable.

fix

Return `pubsub.asyncIterableIterator(topic)` as the subscribe method.

Expected subscription resolver to return an AsyncIterator

Returning a plain value instead of an object with a subscribe method.

fix

Use:
  Subscription: {
    somethingChanged: {
      subscribe: () => pubsub.asyncIterableIterator(SOMETHING_CHANGED_TOPIC),
    },
  }

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

graphqlrequiredPeer dependency required for GraphQL schema and resolver types.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/apollographql/graphql-subscriptions ↗

packagegraphql-subscriptions ↗

homepagehttps://github.com/apollographql/graphql-subscriptions#readme ↗