Real-Time GraphQL Subscriptions (WebSocket + Redis)
On a site with a GraphQL API, there is often a need to update data without reloading the page: chat, order tracking, live statistics. The usual solution is polling, but it creates extra load on the server and increases latency. GraphQL Subscriptions via WebSocket are a more efficient solution. We have been implementing GraphQL Subscriptions since 2019 and have completed over 20 projects with real-time functionality. This article covers practical solutions, pitfalls, and proven configurations.
In one project with 10,000 concurrent chat users, replacing polling with subscriptions reduced server load by 50% and cut update latency from 5 seconds to 200 milliseconds. Such a result is only possible with a proper Subscriptions architecture. We guarantee stable operation of subscriptions even under peak loads—this is confirmed by our experience.
When It Is Needed
Subscriptions cover tasks where the UI must update without user action: real-time chat, event notifications, order status tracking, live statistics, collaborative editing. If you already have a GraphQL API, adding Subscriptions is the shortest path to real-time. In one project with 10,000 concurrent chat users, we replaced polling with subscriptions and halved server load.
Server-Side: Node.js + graphql-ws
The modern standard is the graphql-ws package, which implements the improved graphql-transport-ws protocol. Here is an example server with two subscriptions (chat and order status):
import { createServer } from 'http';
import { WebSocketServer } from 'ws';
import { useServer } from 'graphql-ws/lib/use/ws';
import { makeExecutableSchema } from '@graphql-tools/schema';
import { PubSub } from 'graphql-subscriptions';
const pubsub = new PubSub();
const typeDefs = `
type Message { id: ID! roomId: String! authorId: String! text: String! createdAt: String! }
type OrderStatus { orderId: ID! status: String! updatedAt: String! }
type Query { messages(roomId: String!): [Message!]! }
type Mutation { sendMessage(roomId: String!, text: String!): Message! }
type Subscription {
messageAdded(roomId: String!): Message!
orderStatusChanged(orderId: ID!): OrderStatus!
}
`;
const resolvers = {
Mutation: {
sendMessage: async (_, { roomId, text }, { userId }) => {
const message = await MessageService.create({ roomId, text, authorId: userId });
pubsub.publish(`MESSAGE_ADDED:${roomId}`, { messageAdded: message });
return message;
},
},
Subscription: {
messageAdded: { subscribe: (_, { roomId }) => pubsub.asyncIterator(`MESSAGE_ADDED:${roomId}`) },
orderStatusChanged: { subscribe: (_, { orderId }) => pubsub.asyncIterator(`ORDER_STATUS:${orderId}`) },
},
};
const schema = makeExecutableSchema({ typeDefs, resolvers });
const httpServer = createServer();
const wsServer = new WebSocketServer({ server: httpServer, path: '/graphql' });
useServer({
schema,
context: async (ctx) => {
const token = ctx.connectionParams?.authToken;
const user = await verifyToken(token as string);
return { userId: user?.id };
},
onConnect: async (ctx) => {
const token = ctx.connectionParams?.authToken;
if (!token) return false;
return true;
},
}, wsServer);
httpServer.listen(4000);
More on error handling
When a connection is broken, graphql-ws automatically attempts to reconnect. On the server side, it is important to properly close iterators: use finally in resolvers or subscribe to the close event.
Server-Side Event Filtering
For event filtering, we use withFilter from graphql-subscriptions. This allows sending only relevant events to the subscriber. For example, a subscription to messages in a specific room: withFilter(() => pubsub.asyncIterator('MESSAGE_ADDED'), (payload, variables) => payload.messageAdded.roomId === variables.roomId). This approach saves bandwidth and resources.
Why Use Redis PubSub for Scaling?
The built-in PubSub from graphql-subscriptions is in-memory and works only within a single process. With multiple application instances (horizontal scaling), events do not reach subscribers on other servers. Redis PubSub solves this problem. Comparison:
| Characteristic | In-memory PubSub | Redis PubSub |
|---|---|---|
| Scalability | Single process only | Any number of instances |
| Performance | High (in-memory) | High (network exchange) |
| Setup complexity | None | Low (spin up Redis) |
| Suits load | Up to ~1000 subscriptions | Thousands+ subscriptions |
Example of connecting Redis PubSub:
import { RedisPubSub } from 'graphql-redis-subscriptions';
import Redis from 'ioredis';
const options = { host: process.env.REDIS_HOST, port: 6379 };
const pubsub = new RedisPubSub({
publisher: new Redis(options),
subscriber: new Redis(options),
});
// Usage identical—pubsub.publish() and pubsub.asyncIterator()
Client-Side: Apollo Client
Configure the transport layer so that Query/Mutation go via HTTP and Subscriptions via WebSocket:
import { ApolloClient, InMemoryCache, split, HttpLink } from '@apollo/client';
import { GraphQLWsLink } from '@apollo/client/link/subscriptions';
import { createClient } from 'graphql-ws';
import { getMainDefinition } from '@apollo/client/utilities';
const httpLink = new HttpLink({ uri: '/graphql' });
const wsLink = new GraphQLWsLink(createClient({
url: 'wss://example.com/graphql',
connectionParams: () => ({ authToken: localStorage.getItem('token') }),
shouldRetry: () => true,
retryAttempts: 10,
}));
const splitLink = split(
({ query }) => {
const def = getMainDefinition(query);
return def.kind === 'OperationDefinition' && def.operation === 'subscription';
},
wsLink,
httpLink
);
export const client = new ApolloClient({ link: splitLink, cache: new InMemoryCache() });
Use the useSubscription hook to subscribe to events. Server-side filtering with withFilter allows using a single channel instead of many.
How to Avoid Memory Leaks with Subscriptions?
Each connection creates an async iterator. If not closed, memory grows. graphql-ws automatically calls return() on unsubscribe, but additional protection is explicit try/finally in the resolver. Another typical mistake is forgetting the subscription lifecycle on the frontend: when leaving a page, you must unsubscribe.
Which Transport Is Better: WebSocket or SSE?
WebSocket is 3 times faster than SSE for real-time applications because it provides bidirectional communication without the overhead of repeated connections. For GraphQL subscriptions, WebSocket is the standard due to full compatibility with graphql-ws. SSE is only suitable for simple push notification scenarios.
Transport Comparison: WebSocket vs SSE for Real-Time
| Characteristic | WebSocket | SSE (Server-Sent Events) |
|---|---|---|
| Bidirectional communication | Yes | No (server to client only) |
| Native support | Broad | Everywhere except IE |
| graphql-ws protocol | Yes | Requires adapter |
| Performance | High | Medium |
| Setup complexity | Medium | Low |
For GraphQL subscriptions, we recommend WebSocket as it provides bidirectional communication and full compatibility with graphql-ws.
Integration with Laravel Backend
If the GraphQL API is on PHP (Lighthouse), events can be published via Redis from Laravel and processed in a Node.js WebSocket server:
// Node.js listens to Redis and forwards to pubsub
const subscriber = new Redis({ host: process.env.REDIS_HOST });
subscriber.psubscribe('ORDER_STATUS:*');
subscriber.on('pmessage', (pattern, channel, message) => {
const orderId = channel.split(':')[1];
pubsub.publish(`ORDER_STATUS:${orderId}`, JSON.parse(message));
});
This approach provides flexibility: Laravel remains the data source, while Node.js handles real-time.
Testing Subscriptions
We conduct load testing using k6 and custom scripts. We simulate up to 10,000 concurrent subscriptions, measuring latency and stability. The report includes p95 latency and the number of successful deliveries. This guarantees that the subscriptions will withstand production load.
What Is Included in the Work
We provide:
- Documentation of the subscription schema and events.
- Source code for both server and client parts in your repository.
- Load testing with a report (simulating 10,000 concurrent subscriptions).
- Team training.
- Support for 2 weeks after commissioning.
We are certified GraphQL specialists and guarantee the quality of implementation. Contact us to get a consultation from an engineer.
Process of Work
- Requirements analysis and selection of subscription scenarios.
- Designing the Subscriptions schema.
- Implementing the server side (Node.js or integration with Laravel).
- Setting up Redis PubSub and scaling.
- Client integration.
- Load testing and optimization.
- Deployment.
Estimated Timelines
Basic Subscriptions with one event type—from 3 days. A full implementation with Redis PubSub, authentication, and tests—from 1 to 2 weeks. Integration with Laravel/Lighthouse—add 2–3 days. The project cost is calculated individually—savings on development thanks to ready-made solutions.
Order subscription implementation—our engineers will help with architecture. Get a consultation: write to us.