Subscriptions & Real-Time — GraphQL Fundamentals | Sabaoon Academy

GraphQL subscriptions push data to clients over a persistent WebSocket connection. When a mutation triggers an event, every subscribed client receives the update instantly.

Server Setup

Install the WebSocket transport:

npm install graphql-ws ws @graphql-tools/schema

Update your server to handle both HTTP and WebSocket connections:

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 = `#graphql
  type Message {
    id:        ID!
    text:      String!
    sender:    String!
    createdAt: String!
  }

  type Query {
    messages: [Message!]!
  }

  type Mutation {
    sendMessage(text: String!, sender: String!): Message!
  }

  type Subscription {
    messageSent: Message!
  }
`;

const messages = [];
let nextId = 1;

const resolvers = {
  Query: {
    messages: () => messages,
  },
  Mutation: {
    sendMessage: (_, { text, sender }) => {
      const message = {
        id: String(nextId++),
        text,
        sender,
        createdAt: new Date().toISOString(),
      };
      messages.push(message);
      pubsub.publish('MESSAGE_SENT', { messageSent: message });
      return message;
    },
  },
  Subscription: {
    messageSent: {
      subscribe: () => pubsub.asyncIterator(['MESSAGE_SENT']),
    },
  },
};

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

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

Client Subscription

import { useSubscription, gql } from '@apollo/client';

const MESSAGE_SENT = gql`
  subscription OnMessageSent {
    messageSent {
      id text sender createdAt
    }
  }
`;

function ChatMessages() {
  const [messages, setMessages] = useState([]);

  useSubscription(MESSAGE_SENT, {
    onData: ({ data }) => {
      setMessages(prev => [...prev, data.data.messageSent]);
    },
  });

  return (
    <ul>
      {messages.map(msg => (
        <li key={msg.id}>
          <strong>{msg.sender}:</strong> {msg.text}
        </li>
      ))}
    </ul>
  );
}

Simulating Real-Time in the Browser

Ctrl+Enter

HTML

CSS

* { box-sizing: border-box; margin: 0; padding: 0; }
body { font-family: sans-serif; padding: 1rem; background: #f5f5f5; }

.chat {
max-width: 480px;
border: 1px solid #e5e7eb;
display: flex; flex-direction: column;
background: white; height: 340px;
}

.header {
padding: 0.625rem 0.875rem;
background: #e535ab; color: white;
font-size: 0.85rem; font-weight: 600;
}

.messages {
flex: 1; overflow-y: auto;
padding: 0.75rem;
list-style: none;
display: flex; flex-direction: column; gap: 0.4rem;
}

.msg { padding: 0.4rem 0.625rem; background: #f3f4f6; max-width: 80%; }
.msg.own { background: #fce7f3; align-self: flex-end; }
.msg-sender { font-size: 0.7rem; font-weight: 600; color: #6b7280; }
.msg-text   { font-size: 0.875rem; }
.msg-time   { font-size: 0.65rem; color: #9ca3af; margin-top: 0.15rem; }

.input-row {
display: flex; gap: 0.4rem;
padding: 0.5rem 0.75rem;
border-top: 1px solid #e5e7eb;
}

input {
padding: 0.375rem 0.5rem;
border: 1px solid #d1d5db; font-size: 0.8rem;
flex: 1;
}

button {
padding: 0.375rem 0.75rem;
background: #e535ab; color: white;
border: none; cursor: pointer; font-size: 0.8rem;
}

var messageList = document.getElementById('messages');

// Simulate incoming subscription events
var botMessages = [
{ sender: 'Alice', text: 'Hey! Is the GraphQL server ready?' },
{ sender: 'Bob',   text: 'Subscriptions are so smooth.' },
{ sender: 'Alice', text: 'Way better than polling every 5s!' },
];
var botIndex = 0;

function simulateIncoming() {
if (botIndex < botMessages.length) {
  var m = botMessages[botIndex++];
  addMessage(m.sender, m.text, false);
  setTimeout(simulateIncoming, 2500);
}
}

document.getElementById('form').addEventListener('submit', function(e) {
e.preventDefault();
var sender = document.getElementById('sender').value || 'You';
var text   = document.getElementById('text').value.trim();
if (!text) return;
addMessage(sender, text, true);
document.getElementById('text').value = '';
console.log('mutation: sendMessage(text: "' + text + '", sender: "' + sender + '")');
});

// Start with a welcome message, then simulate incoming
addMessage('System', 'Connected to GraphQL subscription ✓', false);
setTimeout(simulateIncoming, 1200);

Preview

PubSub in Production

The built-in PubSub from graphql-subscriptions is in-memory — it doesn't work across multiple server instances. For production, replace it with a Redis-backed PubSub:

npm install graphql-redis-subscriptions ioredis

import { RedisPubSub } from 'graphql-redis-subscriptions';
const pubsub = new RedisPubSub({
  connection: { host: 'localhost', port: 6379 }
});

Now publish and subscribe work across any number of server processes.

When to Use Subscriptions

Use case	Recommendation
Chat messages	Subscription ✓
Live notifications	Subscription ✓
Dashboard that refreshes every 30s	Polling is simpler
Collaborative editing	Subscription ✓
Long-running job status	Subscription or polling

Subscriptions add complexity (WebSocket infrastructure, connection management). Use them when truly real-time behaviour is required.