This week, I found myself wrestling with a common challenge: building a real-time notification system for a client’s collaborative platform. The requirement was straightforward—users needed instant updates without constantly refreshing their browsers—but the implementation path was less clear. After evaluating several options, I kept coming back to the power and elegance of GraphQL subscriptions. When combined with TypeScript’s type safety and Redis’s scalability, it creates a formidable stack for real-time features. I want to walk you through how to build this for your own projects.

Have you ever considered what makes a real-time API truly reliable at scale?

Let’s start with the foundation. GraphQL subscriptions are fundamentally different from queries and mutations. They use WebSockets to maintain a persistent connection, allowing the server to push data to clients the moment an event occurs. This eliminates the need for inefficient polling, where clients repeatedly ask the server for updates. The result is a more responsive application and reduced server load.

Setting up a project with the right tools is crucial. I prefer using Apollo Server for its robust subscription support. Here’s a basic setup to get you started.

import { ApolloServer } from 'apollo-server-express';
import { createServer } from 'http';
import express from 'express';

const app = express();
const httpServer = createServer(app);

const server = new ApolloServer({
  typeDefs,
  resolvers,
  plugins: [/* Apollo Server plugins */],
  context: ({ req, connection }) => {
    // Build your context here for authentication
  },
});

await server.start();
server.applyMiddleware({ app });
server.installSubscriptionHandlers(httpServer);

httpServer.listen({ port: 4000 }, () =>
  console.log(`Server ready at http://localhost:4000${server.graphqlPath}`)
);

The real magic begins when you define your schema. Type safety is not a luxury; it’s a necessity for maintaining complex applications. I use GraphQL Code Generator to automatically create TypeScript types from my GraphQL schema. This ensures my resolvers are type-safe from the start.

type Subscription {
  messageAdded(channelId: ID!): Message!
  userTyping(channelId: ID!): UserTypingEvent!
}

type UserTypingEvent {
  user: User!
  channelId: ID!
  isTyping: Boolean!
}

Generating types is a single command away.

npx graphql-codegen --config codegen.yml

With the types in place, your resolver signatures become precise and reliable.

import { Resolvers } from './generated/graphql';

const resolvers: Resolvers = {
  Subscription: {
    messageAdded: {
      subscribe: withFilter(
        () => pubSub.asyncIterator(['MESSAGE_ADDED']),
        (payload, variables) => {
          return payload.messageAdded.channelId === variables.channelId;
        }
      ),
    },
  },
};

A single server instance works for development, but what happens when you need to scale? This is where Redis becomes indispensable. Using Redis Pub/Sub allows multiple server instances to communicate about events. A message published from one instance is received by all others, ensuring every subscribed client gets their update, no matter which server they’re connected to.

import Redis from 'ioredis';

const pubSub = {
  publish: (trigger: string, payload: any) => {
    redis.publish(trigger, JSON.stringify(payload));
  },
  subscribe: (trigger: string, onMessage: (message: any) => void) => {
    redis.subscribe(trigger);
    redis.on('message', (channel, message) => {
      if (channel === trigger) {
        onMessage(JSON.parse(message));
      }
    });
  },
  asyncIterator: (trigger: string) => {
    // Returns an AsyncIterator for GraphQL subscriptions
  },
};

How do you manage user authentication over a WebSocket connection? It’s a critical question for security. The connection initializes with an HTTP request, which is your opportunity to validate a user’s token. Once authenticated, that user’s context is available for the life of the subscription.

Handling errors and managing connections gracefully is just as important as the core functionality. You must plan for scenarios like network timeouts, client disconnections, and server failures. Implementing proper cleanup prevents memory leaks and ensures system stability.

Building this type of system is a rewarding experience that elevates your applications. The combination of GraphQL’s declarative data fetching, TypeScript’s compile-time safety, and Redis’s distributed messaging creates a production-ready real-time API.

What real-time feature would you build first with this stack?

If you found this guide helpful, please share it with your network. I’d love to hear about your experiences and answer any questions in the comments below. Let’s build more responsive applications together.