GraphQL Subscriptions

GraphQL Subscriptions

Implement real-time data streaming with GraphQL subscriptions over WebSocket connections

When to Use

• Pushing live updates to clients (chat messages, notifications, live scores)
• Replacing polling for frequently changing data
• Building collaborative features (shared cursors, live editing)
• Streaming long-running operation progress to the client

Instructions

1. Define subscription types in the schema. Subscriptions are root-level operations alongside Query and Mutation.

type Subscription {
  messageAdded(channelId: ID!): Message!
  orderStatusChanged(orderId: ID!): Order!
}

type Message {
  id: ID!
  content: String!
  author: User!
  createdAt: DateTime!
}

2. Use graphql-ws for the WebSocket transport. The older subscriptions-transport-ws is unmaintained. graphql-ws implements the GraphQL over WebSocket protocol correctly with proper connection lifecycle handling.

npm install graphql-ws ws

3. Set up the WebSocket server alongside your HTTP server.

import { createServer } from 'http';
import { WebSocketServer } from 'ws';
import { useServer } from 'graphql-ws/lib/use/ws';
import { ApolloServer } from '@apollo/server';
import { expressMiddleware } from '@apollo/server/express4';
import { makeExecutableSchema } from '@graphql-tools/schema';

const schema = makeExecutableSchema({ typeDefs, resolvers });
const httpServer = createServer(app);

const wsServer = new WebSocketServer({
  server: httpServer,
  path: '/graphql',
});

const serverCleanup = useServer(
  {
    schema,
    context: async (ctx) => {
      const token = ctx.connectionParams?.authToken;
      return { currentUser: await authenticate(token as string) };
    },
  },
  wsServer
);

const server = new ApolloServer({
  schema,
  plugins: [
    {
      async serverWillStart() {
        return {
          async drainServer() {
            await serverCleanup.dispose();
          },
        };
      },
    },
  ],
});

4. Implement a PubSub system for publishing events. Use an in-memory PubSub for development and a distributed backend (Redis, Kafka) for production.

import { PubSub } from 'graphql-subscriptions';

// Development only — in-memory, single-process
const pubsub = new PubSub();

// Production — use Redis-backed PubSub
import { RedisPubSub } from 'graphql-redis-subscriptions';
const pubsub = new RedisPubSub({
  connection: { host: 'redis', port: 6379 },
});

5. Write subscription resolvers with subscribe and optional resolve. The subscribe function returns an AsyncIterator. The resolve function transforms the published payload before sending to the client.

const resolvers = {
  Subscription: {
    messageAdded: {
      subscribe: (_parent, { channelId }, { pubsub }) => {
        return pubsub.asyncIterator(`MESSAGE_ADDED.${channelId}`);
      },
      resolve: (payload) => payload.messageAdded,
    },
  },
  Mutation: {
    sendMessage: async (_parent, { input }, { pubsub, dataSources }) => {
      const message = await dataSources.messages.create(input);
      await pubsub.publish(`MESSAGE_ADDED.${input.channelId}`, {
        messageAdded: message,
      });
      return message;
    },
  },
};

6. Filter subscriptions with withFilter. Only push events that match the subscriber's criteria — do not send all events and let the client discard irrelevant ones.

import { withFilter } from 'graphql-subscriptions';

const resolvers = {
  Subscription: {
    orderStatusChanged: {
      subscribe: withFilter(
        () => pubsub.asyncIterator('ORDER_STATUS_CHANGED'),
        (payload, variables) => payload.orderStatusChanged.id === variables.orderId
      ),
    },
  },
};

7. Authenticate on the WebSocket connection, not per message. Extract the auth token from connectionParams during the initial WebSocket handshake. Reject unauthenticated connections in the onConnect handler.

8. Handle client-side subscriptions with useSubscription or subscribeToMore.

// Standalone subscription
const { data } = useSubscription(MESSAGE_ADDED, {
  variables: { channelId },
});

// Augment an existing query with live updates
const { subscribeToMore, data } = useQuery(GET_MESSAGES, { variables: { channelId } });

useEffect(() => {
  return subscribeToMore({
    document: MESSAGE_ADDED,
    variables: { channelId },
    updateQuery: (prev, { subscriptionData }) => ({
      messages: [...prev.messages, subscriptionData.data.messageAdded],
    }),
  });
}, [channelId, subscribeToMore]);

Details

In-memory PubSub limitations: The default PubSub from graphql-subscriptions works only within a single Node.js process. In a multi-instance deployment, subscribers on one instance will not receive events published by another. Use Redis, Kafka, or Google PubSub for production.

Connection lifecycle: graphql-ws supports onConnect (authentication, rate limiting), onDisconnect (cleanup), and onSubscribe (per-subscription validation). Use these hooks for access control.

Scaling considerations:

• Each active subscription holds an open WebSocket connection — plan for connection limits
• Use Redis PubSub for horizontal scaling across server instances
• Consider connection pooling and heartbeat intervals to detect stale connections
• Load balancers must support WebSocket upgrade (sticky sessions or Layer 4 balancing)

Alternatives to subscriptions:

• Server-Sent Events (SSE) for one-way streaming without WebSocket infrastructure
• @defer and @stream directives for incremental delivery of query results (experimental)
• Polling with cache-and-network for simple cases with moderate freshness needs

Source

https://the-guild.dev/graphql/ws

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.