Week 10: Real-Time Features with WebSockets & Socket.IO

1. WebSockets vs. HTTP Polling

The simplest way to fake real-time updates is polling: the client sends a new HTTP request every few seconds asking "anything new?" Every single poll pays the full cost of an HTTP request — headers, a new connection or at best a reused keep-alive one, a full response — even when the answer is "no, nothing changed." At scale, most of that traffic is pure overhead for a "no."

Long polling improves on this: the server holds the request open without responding until there's actually something new to send, then the client immediately reopens a new request. It reduces wasted round-trips but still pays per-request overhead and doesn't let the server push data outside of an open request.

A WebSocket is a different protocol entirely. It starts as a normal HTTP request that asks to be upgraded to a WebSocket connection — the same handshake you'd see in raw headers below — and once the server accepts, that single TCP connection stays open and becomes full-duplex: either side can send a message to the other at any time, with none of the per-message HTTP header overhead.

GET /socket.io/?EIO=4&transport=websocket HTTP/1.1
Host: api.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Version: 13

--- server responds, connection is now upgraded ---

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

2. Setting Up Socket.IO with Express

Socket.IO is a library built on top of WebSockets that adds automatic reconnection, fallback transports for restrictive networks, and a simple event-based API, at the cost of needing both a matching server and client library rather than being a raw browser WebSocket. Because Socket.IO needs to intercept the HTTP upgrade handshake itself, it attaches to a raw http.Server — not directly to the Express app object, which is just a request handler function.

npm install socket.io
npm install -D @types/node

import { createServer } from "node:http";
import { Server } from "socket.io";
import { createApp } from "./app.js";

const app = createApp();
const httpServer = createServer(app); // Express app is just a request handler
const io = new Server(httpServer, {
  cors: { origin: process.env.CLIENT_ORIGIN ?? "http://localhost:5173" },
});

io.on("connection", (socket) => {
  console.log(`client connected: ${socket.id}`);

  socket.on("disconnect", (reason) => {
    console.log(`client disconnected: ${socket.id} (${reason})`);
  });
});

const port = process.env.PORT ?? 3000;
httpServer.listen(port, () => {
  console.log(`Server (HTTP + WebSocket) listening on port ${port}`);
});

On the client side, the socket.io-client package connects to that same server and reconnects automatically if the connection drops:

import { io } from "socket.io-client";

export const socket = io("http://localhost:3000", {
  autoConnect: true,
});

socket.on("connect", () => {
  console.log("connected with id", socket.id);
});

socket.on("connect_error", (err) => {
  console.error("connection failed:", err.message);
});

3. Rooms & Namespaces

Broadcasting every event to every connected client doesn't scale to a real application — a user viewing order #123 shouldn't receive updates for order #456. Socket.IO's rooms solve this: any connected socket can join an arbitrary named room, and you can then target messages at just that room instead of every client.

io.on("connection", (socket) => {
  socket.on("order:subscribe", (orderId: string) => {
    socket.join(`order-${orderId}`);
  });

  socket.on("order:unsubscribe", (orderId: string) => {
    socket.leave(`order-${orderId}`);
  });
});

Once sockets are in a room, two related methods send to it — the distinction between them matters:

io.on("connection", (socket) => {
  socket.on("order:comment", ({ orderId, text }: { orderId: string; text: string }) => {
    // socket.to(room) sends to everyone in the room EXCEPT this socket --
    // useful so the sender doesn't receive an echo of their own event.
    socket.to(`order-${orderId}`).emit("order:new-comment", { text });

    // io.to(room) sends to EVERYONE in the room, including the sender.
    // Correct when the server is the source of truth and every client,
    // sender included, should get the canonical update.
  });
});

Namespaces are a coarser-grained split — separate communication channels over the same underlying connection, each with its own set of rooms and event listeners. They're useful for separating unrelated real-time features (say, an /orders namespace and a /chat namespace) so each can have distinct authentication and event handling without one polluting the other.

const ordersNamespace = io.of("/orders");

ordersNamespace.on("connection", (socket) => {
  socket.on("order:subscribe", (orderId: string) => {
    socket.join(`order-${orderId}`);
  });
});

// Client connects to it explicitly: io("http://localhost:3000/orders")

4. Broadcasting on Server-Side State Changes

The real payoff of all this is tying Socket.IO into your existing REST routes: when a regular HTTP request changes state in the database, the same handler can broadcast that change to any client subscribed to it, without the client ever needing to poll. That means the io instance needs to be reachable from your Express route handlers — app.set()/app.get() is a clean way to do that without introducing a global.

const app = createApp();
const httpServer = createServer(app);
const io = new Server(httpServer, { cors: { origin: process.env.CLIENT_ORIGIN } });

app.set("io", io); // make it reachable from route handlers via req.app.get("io")

import { Router } from "express";
import type { Server } from "socket.io";
import { updateOrderStatus } from "../services/orders.js";

export const ordersRouter = Router();

ordersRouter.patch("/:id/status", async (req, res, next) => {
  try {
    const order = await updateOrderStatus(req.params.id, req.body.status);

    const io = req.app.get("io") as Server;
    io.to(`order-${order.id}`).emit("order:status-changed", {
      orderId: order.id,
      status: order.status,
      updatedAt: order.updatedAt,
    });

    res.json(order);
  } catch (err) {
    next(err);
  }
});

Every client subscribed to that order's room — regardless of which browser tab or device opened the connection — receives order:status-changed the instant this route runs, with no polling involved on the client at all:

import { socket } from "./socket.js";

export function trackOrder(orderId: string, onUpdate: (status: string) => void) {
  socket.emit("order:subscribe", orderId);

  socket.on("order:status-changed", (payload: { orderId: string; status: string }) => {
    if (payload.orderId === orderId) {
      onUpdate(payload.status);
    }
  });

  return () => {
    socket.emit("order:unsubscribe", orderId);
  };
}

5. Hands-on Exercise

6. Knowledge Check

Four quick questions. Expand each to check your answer.