Real-Time Features — WebSockets and Server-Sent Events

Push live updates to users with server-sent events and WebSockets, choose between them, and scale real-time connections.

Est. 35 min Updated Suggest a fix
// Part 01 — Choose the interaction

Real-Time Does Not Mean the Same Transport Everywhere

Most web requests follow a simple pattern: the browser asks for something and the server replies. A live feature needs the server to deliver a change while the page is still open. Think of a student dashboard that updates a course import, a Swiggy-style delivery tracker showing a status change, or a collaborative editor displaying a teammate's cursor. First decide what changes, who may see it, and how quickly it must appear; then choose the transport.

Start with a durable source of truth, usually the database. A real-time message is a notification that something changed, not a replacement for saving that change. If a browser disconnects, it should be able to fetch current state again. This separation makes reconnects, debugging, and recovery much easier.

OptionDirectionGood fitMain trade-off
PollingBrowser asks repeatedlySimple status checks; low update frequencyUnneeded requests between changes
Server-Sent Events (SSE)Server to browserProgress, notifications, live dashboardsOne-way stream over HTTP
WebSocketBoth directionsChat, collaboration, interactive sessionsMore connection and protocol work
💡 Note
Real-time delivery is usually best-effort. Persist the business action first, then publish an event. If event delivery fails, the page can refresh from the database instead of losing the user's actual work.
// Part 02 — Define the event

Design a Small, Versioned Message Contract

An event should say what happened, identify the affected resource, and carry only the data its authorized recipients need. Do not send an entire database record by default. Use stable event names and identifiers, validate messages on both sides, and think about whether consumers can safely receive the same event twice.

src/realtime/order-events.ts
typescript
import { z } from "zod"

export const orderStatusEventSchema = z.object({
  eventId: z.string().min(1),
  orderId: z.string().min(1),
  status: z.enum(["placed", "preparing", "out_for_delivery", "delivered"]),
  occurredAt: z.string().datetime(),
})

export type OrderStatusEvent = z.infer<typeof orderStatusEventSchema>

export function serializeOrderStatus(event: OrderStatusEvent): string {
  const valid = orderStatusEventSchema.parse(event)
  return JSON.stringify(valid)
}

This contract deliberately omits a customer address, phone number, payment details, and internal notes. The server should check ownership before publishing, not rely on the client to hide fields. An event ID lets a consumer detect duplicates; a timestamp helps with display, but should not be treated as a perfectly ordered global clock.

🎯 Pro Tip
Include a schema version when messages must survive independent deployments. During a rollout, old and new servers may run at the same time, so avoid changing a field's meaning without a compatible migration plan.
// Part 03 — SSE server

Send One-Way Updates with Server-Sent Events

SSE is a long-lived HTTP response with the content type text/event-stream. The browser's built-in EventSource reconnects after many dropped connections and understands event names, IDs, and retry hints. It is a good fit when the browser mostly listens and sends user actions through ordinary HTTP endpoints.

This Express example keeps subscribers in process to make the stream lifecycle visible. The authentication, ownership, and publisher functions are application services; implement them with the session and database patterns from the earlier lessons. In-memory subscribers are not shared by multiple server instances.

src/routes/order-events.ts
typescript
import { Router, type Request, type Response } from "express"
import type { OrderStatusEvent } from "../realtime/order-events"

const router = Router()
const listeners = new Map<string, Set<Response>>()

router.get("/orders/:orderId/events", async (request: Request, response: Response) => {
  const user = await requireSignedInUser(request)
  const orderId = request.params.orderId
  await assertCanViewOrder(user.id, orderId)

  response.status(200).set({
    "Content-Type": "text/event-stream; charset=utf-8",
    "Cache-Control": "no-cache, no-transform",
    "X-Content-Type-Options": "nosniff",
  })
  response.flushHeaders()
  response.write("retry: 3000\n\n")

  const group = listeners.get(orderId) ?? new Set<Response>()
  group.add(response)
  listeners.set(orderId, group)

  const heartbeat = setInterval(() => response.write(": keepalive\n\n"), 20000)
  response.on("close", () => {
    clearInterval(heartbeat)
    group.delete(response)
    if (group.size === 0) listeners.delete(orderId)
  })
})

export function publishOrderStatus(event: OrderStatusEvent) {
  const group = listeners.get(event.orderId)
  if (!group) return

  const payload = JSON.stringify(event)
  for (const response of group) {
    if (response.destroyed || response.writableEnded) {
      group.delete(response)
      continue
    }
    response.write("id: " + event.eventId + "\n")
    response.write("event: order.status\n")
    response.write("data: " + payload + "\n\n")
  }
}

The route checks identity and order ownership before opening a stream. In a real application, cap connections per account, handle errors from the authorization service, and verify how your reverse proxy handles buffering and idle timeouts. A heartbeat helps keep some intermediaries from treating an active stream as idle; it does not guarantee that every network will stay connected.

// Part 04 — SSE client

Subscribe in React and Always Close the Stream

Create the subscription in an effect because it is an external connection, and close it in the cleanup function. Validate incoming data before using it. Same-origin EventSource requests can use the browser's normal cookie session; the API still must authorize the requested order. Native EventSource does not let you set arbitrary request headers, so do not put a reusable bearer token into a query string as a workaround.

app/orders/OrderLiveStatus.tsx
tsx
"use client"

import { useEffect, useState } from "react"
import { orderStatusEventSchema } from "@/src/realtime/order-events"

type Props = { orderId: string }

export function OrderLiveStatus({ orderId }: Props) {
  const [status, setStatus] = useState("Loading status…")
  const [connection, setConnection] = useState("connecting")

  useEffect(() => {
    const source = new EventSource(
      "/api/orders/" + encodeURIComponent(orderId) + "/events",
    )
    source.onopen = () => setConnection("connected")
    source.onerror = () => setConnection("reconnecting")
    source.addEventListener("order.status", (message) => {
      try {
        const event = orderStatusEventSchema.parse(JSON.parse(message.data))
        setStatus(event.status.replaceAll("_", " "))
      } catch {
        setConnection("received an invalid update")
      }
    })
    return () => source.close()
  }, [orderId])

  return <p aria-live="polite">Order: {status} ({connection})</p>
}

Reconnection restores the transport, not necessarily every missed business event. When the stream opens again, fetch a fresh order snapshot or send a last-seen event ID that the server can replay from a durable event log. Keep the UI useful while reconnecting and avoid announcing every heartbeat to assistive technology.

📌 Real World Example
For a long-running file import, store the latest state as queued, running, complete, or failed. SSE can make the progress feel immediate, while a normal GET remains the reliable way to recover the current state after the learner returns later.
// Part 05 — WebSocket

Use WebSockets When Both Sides Need to Talk

A WebSocket begins with an HTTP upgrade and then carries messages in both directions on one persistent connection. A collaborative whiteboard can send cursor movements to the server and receive other learners' movements without opening a new request for every small update. Do not use a WebSocket simply because it sounds more advanced: ordinary POST requests plus SSE may be simpler for a notification feed.

Authenticate and authorize during the upgrade, restrict allowed origins for browser clients, set a maximum message size, validate every message, and rate-limit actions. This example shows the upgrade boundary with the popular ws package; the app-specific authorization helpers must verify the cookie session and access to the requested room before the connection is accepted.

src/realtime/websocket-server.ts
typescript
import { WebSocketServer } from "ws"
import type { IncomingMessage, Server } from "node:http"

const webSockets = new WebSocketServer({ noServer: true, maxPayload: 16384 })

export function attachRealtime(server: Server) {
  server.on("upgrade", (request, socket, head) => {
    void authorizeRoomUpgrade(request as IncomingMessage)
      .then(({ userId, roomId }) => {
        webSockets.handleUpgrade(request, socket, head, (client) => {
          webSockets.emit("connection", client, request, { userId, roomId })
        })
      })
      .catch(() => socket.destroy())
  })

  webSockets.on("connection", (client, _request, context) => {
    client.on("message", async (raw) => {
      let message: unknown
      try {
        message = JSON.parse(raw.toString())
      } catch {
        client.close(1007, "Invalid message")
        return
      }

      const parsed = cursorMessageSchema.safeParse(message)
      if (!parsed.success) {
        client.close(1008, "Unsupported message")
        return
      }
      await assertCanEditRoom(context.userId, context.roomId)
      await publishCursor(context.roomId, context.userId, parsed.data)
    })
  })
}

This is an upgrade and message-validation sketch, not a complete chat server: define the context type for your ws version and handle asynchronous failures, membership cleanup, and outgoing delivery. Never trust the room ID or user ID supplied in a message; derive identity from the authenticated connection and re-check permission for sensitive operations.

// Part 06 — Operate

Reconnect, Recover and Scale Beyond One Process

A process-local map works only while one process owns every connection and every publication. Once you run multiple instances, a user may connect to instance A while an order update reaches instance B. Use a shared broker or managed realtime service to fan out notifications. Keep durable state in the database; a pub/sub broker distributes live messages but may not retain them for offline clients.

  1. Commit the business state change and an event record in one database transaction when missed publication would matter.
  2. Publish from a worker or transactional outbox so a process crash cannot silently separate the database write from the notification.
  3. Route events through a shared broker to the instances that hold subscribers, and partition or authorize by resource.
  4. On reconnect, fetch a fresh snapshot or replay events after a durable cursor; make client updates idempotent.
  5. Track active connections, reconnects, send failures, queue depth, and end-to-end update delay without logging private payloads.
ConcernPractical response
Dropped connectionReconnect with bounded backoff; refresh the current snapshot
Duplicate or late eventDeduplicate by ID and ignore state transitions older than the current version
Slow consumerBound queues; drop replaceable presence updates or disconnect and resync
Many server instancesUse a shared pub/sub layer or managed connection service
Untrusted event dataValidate schema, authenticate connection, authorize each resource
⚠️ Important
Sticky sessions can help a load balancer keep a connection on one instance, but they do not broadcast updates between instances and do not replace a shared event layer.
// Part 07 — Pitfalls

Common Real-Time Mistakes

Using an in-memory subscriber map as a production event bus

Why: Each process has a different map, so users connected elsewhere never receive the update.

Fix: Use a shared broker or managed realtime service when the app has multiple instances.

Treating a live event as the only copy of a change

Why: Networks disconnect and many transports do not retain messages for offline clients.

Fix: Persist state, then recover by fetching a snapshot or replaying a durable event log.

Broadcasting every update to every connected user

Why: A transport connection does not grant access to every resource.

Fix: Authorize subscriptions and publications against the signed-in user and resource.

Leaving streams or sockets open after navigation

Why: Orphaned connections consume file descriptors, memory, and server capacity.

Fix: Close EventSource in effect cleanup; handle socket close and disconnect paths.

// Part 08 — Practice

Add Live Status to a Study-Plan Import

Practice

A recoverable real-time progress panel

  1. Define a typed import event with an event ID, import ID, status, progress message, and timestamp; validate it at the boundary.
  2. Add an authenticated SSE route that verifies ownership and removes listeners on close.
  3. Build a React status component that subscribes, validates messages, announces state politely, and closes on unmount.
  4. Simulate a dropped connection and confirm the UI can recover by fetching the latest stored import state.
  5. Write down how the design changes when there are two application instances and when an event must be replayed.

Hint: Keep the database as the source of truth. Use a shared broker only when multiple processes or delivery requirements call for it.

🎯 Key Takeaways

  • ✓Polling is simplest for infrequent checks; SSE fits one-way server updates; WebSockets fit low-latency, two-way messages.
  • ✓Design a small validated event contract and authorize every user-to-resource subscription.
  • ✓Persist important changes before publishing notifications; reconnecting clients must be able to recover state.
  • ✓EventSource reconnects automatically, but missed-event replay requires a durable cursor or a fresh snapshot.
  • ✓An in-memory subscriber collection is process-local; use shared fan-out for a multi-instance deployment.
  • ✓Bound connections and queues, clean up on disconnect, and measure reliability without logging private payloads.
  • Further reading: MDN documentation for EventSource, the WebSocket API, and the HTML server-sent events format; consult your current framework and proxy documentation for deployment settings.

Next

What comes next

Ship the app with separate environments, managed PostgreSQL, secure configuration, and post-deploy checks.

Lesson 13 · Deploying a Full-Stack App →

HELP US IMPROVE

How was this lesson?

Your note is shared with the Chaduvuko team for review. Please don’t include personal or sensitive information.

Choose your feedback

Spotted a mistake or something unclear? Suggest a fix on GitHub or email us. Select the text first and it is quoted for you.

Share

Discussion

0

Have a better approach? Found something outdated? Share it — your knowledge helps everyone learning here.

Continue with GitHub
Loading...