GraphQL Subscriptions: WebSocket & Server-Sent Events Guide

GraphQL subscriptions enable real-time data push from server to client. This guide covers when to use subscriptions, how to implement WebSocket and SSE transports, and how to scale across multiple server instances using Redis pub/sub.

Subscription Schema & Resolver

Define subscriptions in the SDL and implement resolvers using AsyncIterator. The PubSub instance manages publish/subscribe internally:

import { PubSub } from 'graphql-subscriptions';
import { gql } from 'graphql-tag';

const pubsub = new PubSub();
const MESSAGE_ADDED = 'MESSAGE_ADDED';

const typeDefs = gql`
  type Message {
    id: ID!
    content: String!
    author: String!
    createdAt: String!
  }

  type Query { messages(channelId: ID!): [Message!]! }

  type Mutation {
    sendMessage(channelId: ID!, content: String!, author: String!): Message!
  }

  type Subscription {
    messageAdded(channelId: ID!): Message!
  }
`;

const resolvers = {
  Mutation: {
    sendMessage: async (_: unknown, args: any) => {
      const message = await db.messages.create(args);
      // Publish to all subscribers of this channel
      await pubsub.publish(`${MESSAGE_ADDED}.${args.channelId}`, {
        messageAdded: message,
      });
      return message;
    },
  },
  Subscription: {
    messageAdded: {
      // AsyncIterator yields events when published
      subscribe: (_: unknown, { channelId }: { channelId: string }) =>
        pubsub.asyncIterator(`${MESSAGE_ADDED}.${channelId}`),
    },
  },
};

Apollo Server with graphql-ws (WebSocket)

Apollo Server 4 requires a separate WebSocket server for subscriptions. Use graphql-ws to handle the WebSocket handshake alongside your HTTP server:

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

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

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

const serverCleanup = useServer({
  schema,
  onConnect: async (ctx) => {
    // Authenticate during WS handshake
    const token = ctx.connectionParams?.authToken as string;
    if (!token) throw new Error('Missing auth token');
    return { user: await validateToken(token) };
  },
}, wsServer);

// HTTP server — handles queries & mutations
const apolloServer = new ApolloServer({
  schema,
  plugins: [
    { async serverWillStart() {
      return { async drainServer() { await serverCleanup.dispose(); } };
    }},
  ],
});

await apolloServer.start();
app.use('/graphql', expressMiddleware(apolloServer));
httpServer.listen(4000);

Scaling with Redis Pub/Sub

Replace the in-memory PubSub with graphql-redis-subscriptions to broadcast events across all server instances:

import { RedisPubSub } from 'graphql-redis-subscriptions';
import Redis from 'ioredis';

// Two Redis clients: one for publish, one for subscribe
const pubsub = new RedisPubSub({
  publisher: new Redis({ host: 'redis', port: 6379 }),
  subscriber: new Redis({ host: 'redis', port: 6379 }),
});

// Drop-in replacement for the in-memory PubSub
// All server instances share the same Redis channel
// Instance A publishes → Redis broadcasts → Instance B/C push to their WS clients

// Use pattern subscriptions for dynamic channels
const asyncIterator = pubsub.asyncIterator(
  `MESSAGE_ADDED.${channelId}`  // per-channel topic
);

// With graphql-subscriptions-filter for server-side filtering:
import { withFilter } from 'graphql-subscriptions';

const resolvers = {
  Subscription: {
    messageAdded: {
      subscribe: withFilter(
        (_: any, { channelId }: any) => pubsub.asyncIterator('MESSAGE_ADDED'),
        (payload: any, variables: any) => payload.messageAdded.channelId === variables.channelId,
      ),
    },
  },
};

WebSocket vs SSE vs Polling for Subscriptions