GraphQL Subscription Best Practices Examples

Production-ready examples demonstrating GraphQL subscription patterns using Apollo Router.

Quick Start

Prerequisites

• Node.js v20+
• Redis (brew install redis on macOS)
• Apollo Router (download)
• Rover CLI (install)

Setup

# Start Redis
redis-server &

# Pick a pattern
cd patterns/1-subscription-broker

# Install dependencies and run
./setup.sh
./start.sh

Patterns

Pattern	Use Case	Complexity
1. Subscription Broker	Broker-based architecture with HTTP callbacks	Medium
2. Guaranteed Delivery	Zero message loss, cursor-based backfill	High
3. WebSocket	Standard WebSocket passthrough	Low

Each pattern is self-contained with its own README, start script, and router configuration.

What's Included

Chat Demo

Each pattern implements a chat app. When you open the frontend, a room ID is auto-generated and a "Mystery User" starts sending messages every 5-15 seconds, demonstrating the subscription flow end-to-end.

Frontend

React + Apollo Client demonstrating:

• HTTP multipart subscriptions
• Connection state tracking
• Automatic reconnection
• Cursor-based resumption (Pattern 2)

Architecture

┌─────────┐  Multipart HTTP   ┌─────────┐   HTTP Callbacks    ┌──────────┐
│  Client │ ◄───────────────► │  Router │ ◄─────────────────► │ Subgraph │
└─────────┘    (always)       └─────────┘   (or WebSocket)    └──────────┘

Client ↔ Router is always multipart HTTP. The callback vs WebSocket choice only affects Router ↔ Subgraph.

Two Heartbeat Mechanisms

Heartbeat	Direction	Mode	Who sends it
Callback heartbeat	Subgraph → Router	HTTP Callback	Your code (Patterns 1-2)
WebSocket ping	Router ↔ Subgraph	WebSocket	Router (Pattern 3)

Project Structure

├── shared/                     # Utility code
└── patterns/
    ├── 1-subscription-broker/  # Each pattern is self-contained
    │   ├── subgraph/           # GraphQL subgraph
    │   ├── subscription-broker/# Broker service (handles callbacks)
    │   ├── mystery-user/       # Simulated chat partner
    │   ├── frontend/           # React + Apollo Client
    │   ├── setup.sh            # Install dependencies
    │   └── start.sh            # Run all services
    ├── 2-guaranteed-delivery/
    │   ├── subgraph/
    │   ├── subscription-broker/
    │   ├── mystery-user/
    │   ├── frontend/
    │   ├── setup.sh
    │   └── start.sh
    └── 3-websocket/
        ├── subgraph/
        ├── mystery-user/
        ├── frontend/
        ├── setup.sh
        └── start.sh

Learn More

• HTTP Callback Protocol Docs
• Each pattern's README contains detailed architecture, configuration, and production considerations