Realtime
Native WebSocket, socket.io-client, SSE, reconnect/auth, React hooks, and Next.js deployment. · 32 lessons · click a card to expand
Transport choice
4 items01HTTP polling: cheap to start, expensive to scale
refetchInterval is polling with a cache. It works for job status, unread counts, and dashboards that can be 10–30 seconds stale.async function pollInbox(userId: string) {
const res = await fetch(`/api/inbox?userId=${userId}`);
if (!res.ok) throw new Error(`poll failed: ${res.status}`);
return res.json() as Promise<{ unread: number; latestId: string | null }>;
}
const timer = window.setInterval(() => {
void pollInbox("u_1").then((data) => {
renderBadge(data.unread);
});
}, 5_000);
// Always clear — a leaked interval is a leaked request storm
window.addEventListener("pagehide", () => clearInterval(timer));The cost is multiplicative. One thousand tabs polling every 5s is 200 requests/second even when nothing changed. You also pay HTTP header overhead, TLS, and origin connection limits. Missed updates sit in the gap between ticks; two updates in one window collapse into one snapshot unless you return a log, not just the latest row.
Use polling when updates are rare, payloads are small, and you already have REST. Do not use it for chat, live cursors, or trading ticks.
ETag / If-None-Match or a since cursor) instead of refetching a huge dashboard every tick./api/unread every 3s. Open DevTools Network, count requests for one minute, then double the interval and compare. Note how many responses were identical.02Long-polling: hold the request until something happens
GET /events?since=42 and the server *does not answer* until event 43 exists or ~25s elapse (under typical proxy idle limits). The client immediately opens the next request. That hang-and-replace loop is how many chat systems worked before WebSockets were universal.async function longPoll(since: number): Promise<void> {
const res = await fetch(`/api/events?since=${since}`, {
signal: AbortSignal.timeout(30_000),
});
if (res.status === 204 || res.status === 408) {
return longPoll(since); // timeout with no data — hang again
}
const batch = (await res.json()) as { id: number; type: string; payload: unknown }[];
for (const event of batch) applyEvent(event);
const next = batch.at(-1)?.id ?? since;
return longPoll(next);
}
void longPoll(0).catch((err) => {
if (err.name !== "AbortError") console.error(err);
});Compared with short polling you waste fewer empty 200s. Compared with WebSocket you still pay a new HTTP handshake (or at least a new request) per event batch, you cannot easily push *from the client* on the same pipe, and intermediaries may still cut the hung request. You also must serialize events so a timeout retry does not skip or double-apply work — the since cursor is the whole protocol.
Long-polling is a fallback, not a destination: socket.io still uses it when a WebSocket upgrade fails (Lesson 23).
awaits a promise resolved by setTimeout or an EventEmitter. Point fetch at it. Kill the server mid-hang and confirm your client retries with the same since.03SSE vs WebSocket vs WebRTC: one-way, two-way, and peer media
EventSource) look like a never-ending HTTP response with Content-Type: text/event-stream. The browser parses data: lines, reconnects for you, and resends Last-Event-ID (Lesson 28). That is why AI chat UIs (this repo’s GenE-style streaming) often pick SSE: the user sends a normal POST to start a job, then the model tokens flow one way.// SSE — server speaks, client only listens
const source = new EventSource("/api/stream?job=42");
source.addEventListener("token", (ev) => {
appendChat(ev.data);
});
// WebSocket — both sides send any time after open
const ws = new WebSocket("wss://api.example.com/ws/dashboard");
ws.addEventListener("open", () => {
ws.send(JSON.stringify({ type: "subscribe", channel: "presence" }));
});
ws.addEventListener("message", (ev) => {
const msg = JSON.parse(ev.data as string);
if (msg.type === "presence") renderPresence(msg.data);
});WebSocket is the default for chat, multiplayer, collaborative cursors, and live ops dashboards (this repo’s TimeLens-style hook). After the 101 upgrade, frames go both ways with little per-message overhead.
WebRTC DataChannels can also send arbitrary bytes, but you need ICE, STUN/TURN, and a signaling channel (often a WebSocket) just to connect two browsers. Use WebRTC for camera, microphone, and screen share; do not pick it as your app’s pub/sub bus.
send. In tab B, open an EventSource to a stream endpoint. Confirm only tab A can send after connect without opening a second HTTP request.04Transport decision table: pick the right pipe
| Need | Polling | Long-poll | SSE | WebSocket | WebRTC |
|---|---|---|---|---|---|
| Unread badge every 30s | Best | Overkill | Overkill | Overkill | No |
| AI token stream, client already POSTed | Poor | OK | Best | Fine | No |
| Chat / live dashboard / subscribe+publish | Poor | Fallback | Half (no up) | Best | Wrong tool |
| Camera / mic / screen | No | No | No | Signaling only | Best |
Custom Authorization header from JS | Yes | Yes | No | Handshake only | Signaling |
| Auto reconnect in the browser platform | You | You | Yes | You | You |
| Works when WS is blocked by a proxy | Yes | Yes | Often | Fails | TURN helps |
| Serverless function as the *socket host* | Yes | Awkward | Awkward | No | No |
type Transport = "poll" | "sse" | "ws" | "webrtc";
function pickTransport(need: {
direction: "down" | "both" | "media";
maxDelayMs: number;
needsAuthHeader: boolean;
}): Transport {
if (need.direction === "media") return "webrtc";
if (need.direction === "down" && need.maxDelayMs > 2_000) {
return need.needsAuthHeader ? "poll" : "sse";
}
return "ws";
}
pickTransport({ direction: "both", maxDelayMs: 200, needsAuthHeader: false }); // "ws"This repo’s production split matches the table: TimeLens uses a native WebSocket hook for bidirectional workforce events; GenE uses SSE for one-way model tokens; Asset360Hub stays on REST + React Query because nothing is live enough to justify a socket.
new WebSocket one-liner.Native WebSocket (no package)
7 items05The handshake: HTTP Upgrade, 101, and then it is no longer HTTP
101 Switching Protocols, the same TCP connection becomes a WebSocket. There is no second URL family beyond ws: / wss:.new WebSocket(url) sends a GET with Upgrade: websocket, Connection: Upgrade, a random Sec-WebSocket-Key, and an optional Sec-WebSocket-Protocol list. The server hashes the key with a RFC 6455 magic string and returns Sec-WebSocket-Accept plus status 101. After that, you do not send HTTP verbs on that socket. You send frames (Lesson 8).const ws = new WebSocket("wss://api.example.com/ws/dashboard/?token=eyJ...");
// You cannot set arbitrary headers here — the browser owns the handshake.
// Cookies for the wss origin are sent automatically (same-site rules apply).
ws.addEventListener("open", () => {
console.log("upgrade succeeded — readyState is OPEN");
});
ws.addEventListener("error", () => {
// Handshake failures often show up as error + close 1006 with no body
console.error("upgrade or transport failed");
});wss: is TLS + WebSocket, the same relationship as https: to http:. Mixed content rules apply: an https page cannot open ws://. This repo builds wss://${process.env.NEXT_PUBLIC_API_URL}/ws/${url}/?token=${token} so the page origin and the API host can differ (cross-origin WebSocket is allowed; CORS does not apply the way fetch does — the server must still authenticate).
If a proxy or serverless platform answers 200 HTML instead of 101, the constructor still fires error/close. There is no response body for you to await.
new WebSocket at a normal https REST URL. Observe error then close with code 1006. Then point it at a real WS echo server and confirm 101 in the Headers pane.06readyState: CONNECTING, OPEN, CLOSING, CLOSED
WebSocket.readyState is a number the browser updates for you. Only OPEN (1) may send. Treating “I constructed it” as “it is connected” is the first production bug.WebSocket.CONNECTING (0), OPEN (1), CLOSING (2), CLOSED (3). Construction starts CONNECTING. onopen means OPEN. close() moves to CLOSING then CLOSED. A failed handshake jumps to CLOSED without a successful OPEN.type SocketStatus = "idle" | "connecting" | "open" | "closed";
function statusFromReadyState(ws: WebSocket | null): SocketStatus {
if (!ws) return "idle";
switch (ws.readyState) {
case WebSocket.CONNECTING:
return "connecting";
case WebSocket.OPEN:
return "open";
case WebSocket.CLOSING:
case WebSocket.CLOSED:
return "closed";
default:
return "closed";
}
}
function safeSend(ws: WebSocket | null, payload: unknown) {
if (!ws || ws.readyState !== WebSocket.OPEN) {
throw new Error("socket is not OPEN");
}
ws.send(JSON.stringify(payload));
}This repo’s hook does not read readyState in the UI. It mirrors it with React state: "idle" | "connecting" | "open" | "closed". idle means “we are not trying” (no token). connecting is set the moment new WebSocket runs. open is set in onopen. closed is set in onclose before the reconnect timer. That extra idle is application state, not a fifth readyState.
Never send in the same tick you construct. Queue (Lesson 15) or send from onopen.
ws.readyState next to your React status. If they disagree, you have a stale wsRef or you called setStatus after unmount (Lesson 20).console.log readyState immediately, in onopen, after close(), and in onclose. You should see 0 → 1 → 2 → 3 on a clean shutdown.07The four events: open, message, error, close
addEventListener equivalents). Production hooks assign all four. error does not include a useful reason; close does.onopen fires once per successful handshake. onmessage fires for every complete application message (event.data is a string, Blob, or ArrayBuffer). onerror fires on failures but the event is nearly empty in browsers — treat it as a log hook. onclose always fires when the socket dies, including after error, including when *you* called close().function attachNativeHandlers(ws: WebSocket) {
ws.onopen = () => {
console.log("open");
};
ws.onmessage = (ev: MessageEvent<string>) => {
try {
const parsed = JSON.parse(ev.data);
console.log("message", parsed);
} catch (err) {
console.error("Failed to parse WS message:", err, ev.data);
}
};
ws.onerror = (e) => {
console.error("WebSocket error:", e);
};
ws.onclose = (event: CloseEvent) => {
console.log("close", event.code, event.reason, event.wasClean);
};
}This is the same quartet as useWebSocket2.ts. The hook wraps each handler with if (!isMountedRef.current) return so a socket that outlives the component cannot setState. onmessage JSON-parses and forwards to onMessage. onclose is where reconnect is scheduled — not onerror. If you reconnect in both, you double-connect.
CloseEvent.wasClean is true when both sides sent a close frame. Abnormal drops (tab kill, network yank, proxy idle) are wasClean === false and usually code 1006.
onmessage and *lifecycle* logic in onopen / onclose. If you mix “resubscribe” into onmessage, you will resubscribe on every chat line.{ type: "ping" } from onopen, log the reply in onmessage, then call ws.close(1000, "done") and record code, reason, and wasClean.08Frames and a JSON application protocol
event.data as a UTF-8 JSON string with a type discriminator. Native WebSocket does not know your events — you invent that protocol.string. Binary frames become Blob by default (ws.binaryType = "arraybuffer" if you want bytes). Control frames (ping/pong/close) are handled by the browser; you do not see ping/pong as message events. Keepalive is therefore either the browser/server ping or an application { type: "ping" } you send yourself (Lesson 10).interface WSMessage {
type?: string;
data?: unknown;
[key: string]: unknown;
}
function encode(msg: WSMessage): string {
return JSON.stringify(msg);
}
function decode(raw: string): WSMessage {
const parsed: unknown = JSON.parse(raw);
if (typeof parsed !== "object" || parsed === null) {
throw new Error("WS payload must be an object");
}
return parsed as WSMessage;
}
// Application protocol — not part of the WebSocket spec
ws.send(encode({ type: "subscribe", data: { channel: "agents.shift" } }));
ws.send(encode({ type: "chat.send", data: { roomId: "r1", body: "hello" } }));This repo’s hook types that envelope as WSMessage and blindly JSON.parses. A good protocol adds type (required), data (payload), and later seq / id (Lesson 16). Version the contract (v: 1) if multiple clients ship. Never concatenate two JSON objects in one frame — one frame, one value.
Binary protocols (protobuf, MessagePack) belong on binaryType = "arraybuffer" when payload size or CPU matters. Start with JSON; switch when you measure.
type values in a default branch. Silent ignore hides server/client skew until a launch.subscribe, event, error — and a switch (msg.type) that exhausts them in TypeScript. Send a fourth type from the server mock and confirm you log it.09Close codes: 1000 is success, 1006 is “we never got a code”
close(code, reason) is how you tell the peer *why*. 1000 is normal. 1001 is going away (tab, server shutdown). 1006 is reserved — the browser sets it when the connection dropped with no close frame.close reason string must be ≤123 UTF-8 bytes. This repo uses 1000 with human reasons: "Tab closed or refreshed", "Token missing - closing", "Component unmounted".ws.close(1000, "Component unmounted");
ws.onclose = (event) => {
switch (event.code) {
case 1000:
console.log("normal:", event.reason);
break;
case 1001:
console.log("peer going away");
break;
case 1008:
console.log("policy / auth rejected");
break;
case 4001:
console.log("app: token expired — do not reconnect");
break;
case 1006:
console.log("abnormal — network, proxy, or failed handshake");
break;
default:
console.log("other", event.code, event.reason);
}
};Use 1000 on intentional client shutdown so the server can drop the session cleanly instead of waiting for a ping timeout. Use an application code (for example 4001) when the server invalidates the JWT so the client *must not* reconnect with the same token — useWebSocket2 approximates that by refusing to reconnect when token is null, not by reading the close code.
Do not call close(1006, ...). The spec forbids sending 1005 or 1006. The UA synthesizes 1006 for you.
code + reason on every close in staging. A flood of 1006 at :30 past the minute is usually a load balancer idle timeout, not your React cleanup.1000 and "done". Then kill the tab without calling close and inspect the server’s received code (or DevTools on a second client). Compare 1000 vs 1006.10Heartbeat: protocol ping/pong vs application ping
close.ws.ping() in page JavaScript. Servers (ws, uWebSockets, Django Channels) should ping clients. If your server already pings, do not also spam application pings every second.When you cannot control the server, send a small JSON ping and expect a pong. If no pong arrives before a deadline, call close() and let your reconnect path run.
function startHeartbeat(ws: WebSocket, onDead: () => void) {
let alive = true;
const pingTimer = window.setInterval(() => {
if (ws.readyState !== WebSocket.OPEN) return;
alive = false;
ws.send(JSON.stringify({ type: "ping", t: Date.now() }));
}, 20_000);
const watchdog = window.setInterval(() => {
if (ws.readyState !== WebSocket.OPEN) return;
if (!alive) {
ws.close(4000, "heartbeat timeout");
onDead();
}
}, 40_000);
const prev = ws.onmessage;
ws.onmessage = (ev) => {
try {
const msg = JSON.parse(ev.data as string) as { type?: string };
if (msg.type === "pong" || msg.type === "ping") alive = true;
} catch {
/* fall through to app parser */
}
prev?.call(ws, ev);
};
return () => {
clearInterval(pingTimer);
clearInterval(watchdog);
};
}useWebSocket2.ts does not implement an application heartbeat. It relies on onclose (including proxy kills) plus backoff. That is acceptable when the server pings; add the snippet above when you see silent stalls with readyState === OPEN and no messages.
proxy_read_timeout, AWS ALB idle, corporate NAT). Measure with a quiet tab left open for an hour.ws server. Disable server pings. After 60s of silence, note whether the client still thinks it is open. Add an application ping and confirm onclose fires when you drop pong replies.11bufferedAmount: stop sending when the pipe is backed up
ws.send is not “the peer has the bytes.” It means “the browser queued them.” bufferedAmount is how many bytes are still sitting in the client’s outbound buffer.send succeeds while bufferedAmount climbs. Memory grows, latency becomes “whatever was queued,” and you still think you are realtime. The fix is to skip, coalesce, or queue-with-drop-old when the buffer is above a threshold.const MAX_BUFFER = 64_000;
function sendMove(ws: WebSocket, point: { x: number; y: number }) {
if (ws.readyState !== WebSocket.OPEN) return;
if (ws.bufferedAmount > MAX_BUFFER) {
// Drop this sample — the next rAF will send a newer point
return;
}
ws.send(JSON.stringify({ type: "cursor", data: point }));
}
function onFrame(ws: WebSocket, point: { x: number; y: number }) {
sendMove(ws, point);
}bufferedAmount resets toward 0 as the network drains. It is not a round-trip ACK. Application-level acks (Lesson 16 / socket.io acks in Lesson 25) tell you the *server* processed a message. Use both: buffer to protect the client, seq/ack to protect the protocol.
This repo’s hook does not expose send — it is receive-only from the React side, which is why TimeLens can skip bufferedAmount until the UI starts publishing.
latestRef.current = point) and send on an interval. That is cheaper than a growing queue of stale cursors.send 1 MB strings without waiting. Log bufferedAmount each iteration. Then gate on bufferedAmount < 16_000 and compare memory in DevTools.Production connections
6 items12Reconnect with exponential backoff and jitter
close thunders a downed server. Double the wait each failure, cap it, and add random jitter so clients do not share one clock.useWebSocket2.ts starts at 1s, doubles after every onclose, and caps at 30s. On onopen it resets to 1s. That is classic exponential backoff. It does not add jitter — every tab that dies together will retry together.const retryDelayRef = { current: 1_000 };
function nextDelay() {
const delay = retryDelayRef.current;
retryDelayRef.current = Math.min(delay * 2, 30_000);
return delay;
}
function nextDelayWithJitter() {
const base = nextDelay();
const jitter = base * (0.5 + Math.random()); // 50–150% of base
return Math.floor(jitter);
}
// useWebSocket2 onclose (no jitter):
// const delay = retryDelayRef.current;
// retryDelayRef.current = Math.min(delay * 2, 30000);
// reconnectTimerRef.current = window.setTimeout(connect, delay);Sequence without jitter: 1s, 2s, 4s, 8s, 16s, 30s, 30s, … Sequence with full jitter: each client picks a different slice of that window. When a deploy restarts the WS process, jitter turns a spike into a ramp.
Never reconnect if the close was intentional (logout, unmount). The repo checks if (!token) return inside onclose and sets isMountedRef.current = false in cleanup so the stale socket cannot schedule connect.
reconnectTimerRef) and clearTimeout on unmount. A timer that outlives the component is a ghost socket (Lesson 20).onclose ten times in a test with fake timers (Lesson 32). Assert delays are 1, 2, 4, … 30, 30. Then add jitter and assert two clients rarely share the exact same timeout.13Auth: query string vs subprotocol vs cookie
WebSocket constructor cannot set Authorization. Teams stuff the JWT into the query string, into Sec-WebSocket-Protocol, or rely on httpOnly cookies on the handshake. This repo uses the query string.useWebSocket2.ts builds wss://${API_URL}/ws/${url}/?token=${token} and refuses to connect when token is null. That matches Django Channels / many Node tutorials. It is also the leaky option: tokens appear in access logs, proxies, browser history, and Referer on some misconfigured assets.// 1) Query string — this repo
const fullUrl = `wss://${API_URL}/ws/${url}/?token=${token}`;
const ws = new WebSocket(fullUrl);
// 2) Subprotocol slot — second constructor argument
// Server must echo one of the protocols. Some stacks treat the first
// value as a bearer token (non-standard but common).
const wsProto = new WebSocket(`wss://${API_URL}/ws/${url}/`, [
"bearer",
token.replace(/\+/g, "-"), // protocols have a limited charset
]);
// 3) Cookie — best when API and page share a site
// `credentials` are automatic for wss on that registrable domain.
const wsCookie = new WebSocket(`wss://api.example.com/ws/${url}/`);Cookie auth (SameSite=Lax/Strict, __Host- prefix, CSRF story for any cookie-authenticated POST) is the clean browser design. Query tokens are fine for first-party internal tools if logs are redacted and tokens are short-lived. Subprotocol auth is a workaround when you cannot share cookies and refuse to log query strings — test it; not every proxy forwards Sec-WebSocket-Protocol the way you hope.
After connect, you can still send { type: "auth", token } as the first message. That avoids logs but leaves a brief unauthenticated socket — the server must timeout if auth never arrives.
token to null so the effect’s “no token” branch runs. Do not leave a socket open with a revoked JWT.14Resubscribe after every reconnect
open are gone. Treat onopen as “replay my subscriptions,” not “I am already subscribed.”useWebSocket2 connects to a path (/ws/${url}/) that may already imply a room. Many APIs still require an explicit { type: "subscribe", channel } because one connection multiplexes many topics. After backoff reconnect, if you do not send those again, the UI looks “connected” (status === "open") while remaining silent.const subscriptionsRef = { current: new Set<string>(["agents.shift", "alerts"]) };
function connect(fullUrl: string) {
const ws = new WebSocket(fullUrl);
ws.onopen = () => {
for (const channel of subscriptionsRef.current) {
ws.send(JSON.stringify({ type: "subscribe", data: { channel } }));
}
};
return ws;
}
function subscribe(ws: WebSocket | null, channel: string) {
subscriptionsRef.current.add(channel);
if (ws?.readyState === WebSocket.OPEN) {
ws.send(JSON.stringify({ type: "subscribe", data: { channel } }));
}
}Keep desired subscriptions in a ref or a store, not only in “what I sent once.” The registry pattern in Lesson 21 is the React version of this set. Server-side, prefer making subscribe idempotent so a double open from StrictMode does not create two consumers.
{ type: "sync", since: lastSeq }) so you heal events missed while disconnected (Lesson 16).subscribe frames on the new socket (DevTools WS messages).15Outbound queue while connecting or closed
OPEN. Buffer outbound messages, flush on onopen, and cap or drop stale ones so a long outage does not replay a megabyte of “typing” events.useWebSocket2 currently returns only { status } — callers do not send. The moment you add send, you need a queue. If you throw when not open, buttons flake during reconnect. If you silently drop, users think the click worked.type Outbound = { type: string; data?: unknown };
const queue: Outbound[] = [];
const MAX_QUEUE = 50;
function enqueue(ws: WebSocket | null, msg: Outbound) {
if (ws?.readyState === WebSocket.OPEN && queue.length === 0) {
ws.send(JSON.stringify(msg));
return;
}
if (queue.length >= MAX_QUEUE) queue.shift(); // drop oldest
queue.push(msg);
}
function flush(ws: WebSocket) {
while (queue.length && ws.readyState === WebSocket.OPEN) {
const next = queue.shift();
if (next) ws.send(JSON.stringify(next));
}
}
ws.onopen = () => {
flush(ws);
};Drop-oldest is correct for cursors and “latest filter.” Drop-newest or “reject send” is correct for payments and chat — those need an error in the UI, not silent loss. Combine with bufferedAmount (Lesson 11) so flush does not dump 50 messages into a saturated buffer.
createdAt. After 30s in the queue, fail them to the UI instead of surprising the server with a fossil.16Sequence numbers, dedupe, and “at least once”
seq per stream and ignore ids you have already applied.since: lastSeq, and the server also replays the last second. Without dedupe, a chat bubble doubles and a reducer increments twice. WebSocket is a byte pipe; it does not give you exactly-once.const seen = new Set<string>();
const SEEN_CAP = 500;
let lastSeq = 0;
function applyEvent(msg: { id: string; seq: number; type: string; data: unknown }) {
if (seen.has(msg.id) || msg.seq <= lastSeq) return;
seen.add(msg.id);
lastSeq = Math.max(lastSeq, msg.seq);
if (seen.size > SEEN_CAP) {
const first = seen.values().next().value;
if (first) seen.delete(first);
}
switch (msg.type) {
case "chat":
appendChat(msg.data);
break;
default:
break;
}
}
ws.onopen = () => {
ws.send(JSON.stringify({ type: "sync", since: lastSeq }));
};Idempotent handlers are even better: applying the same “set slot X to booked” twice is a no-op. Use seq for ordering (“ignore older occupancy”) and ids for exact dupes. Persist lastSeq in memory only unless you must survive a full page reload — then store it in sessionStorage keyed by user + topic.
Date.now() as an id. Two events in the same millisecond collide. Use server-generated ids.{ id: "e1", seq: 1 } into applyEvent twice and a { id: "e2", seq: 0 } once. Only the first e1 should change UI state.17online / offline and page visibility
onclose is not the only signal. The browser knows the network dropped (offline) and when the tab is hidden. Use those to pause heartbeats, close cleanly, and reconnect immediately when the user comes back.window.addEventListener("offline") fires when the UA believes there is no network. Sockets often sit in OPEN until a send or ping fails — you can close yourself to skip the heartbeat timeout. online is the moment to reset backoff to 1s and call connect() if status !== "open" and you still have a token.function attachNetworkHooks(connect: () => void, disconnect: () => void) {
const onOffline = () => disconnect();
const onOnline = () => connect();
window.addEventListener("offline", onOffline);
window.addEventListener("online", onOnline);
document.addEventListener("visibilitychange", () => {
if (document.visibilityState === "visible") onOnline();
});
return () => {
window.removeEventListener("offline", onOffline);
window.removeEventListener("online", onOnline);
};
}useWebSocket2.ts does not listen to online/offline or visibilitychange. It *does* listen to beforeunload and pagehide to close with 1000 (Lesson 20). That covers tab close and iOS Safari backgrounding better than beforeunload alone. Adding online is the usual next step when reconnect feels “stuck” after a laptop sleep.
Do not spin a new socket on every visibilitychange if you are already OPEN — check readyState / React status first.
visibilitychange → visible.offline, onclose, and online order. Then background the tab on a phone and see whether pagehide fires (it often does; beforeunload often does not).React: `useWebSocket` like this repo
5 items18Build useWebSocket: token, URL, and status
wss://${API_URL}/ws/${url}/?token=${token}, parses JSON messages, and returns { status }. No token means no socket.src/hooks/useWebSocket2.ts is "use client". It takes url (path segment), token (string | null), and onMessage. Refs hold the socket, the retry delay, the reconnect timer, and a mount flag. React state is only the four-way status."use client";
import { useEffect, useRef, useState } from "react";
interface WSMessage {
type?: string;
data?: unknown;
[key: string]: unknown;
}
const API_URL = process.env.NEXT_PUBLIC_API_URL;
export function useWebSocket(
url: string,
token: string | null,
onMessage: (msg: WSMessage) => void,
) {
const wsRef = useRef<WebSocket | null>(null);
const [status, setStatus] = useState<"idle" | "connecting" | "open" | "closed">("idle");
const retryDelayRef = useRef(1000);
const reconnectTimerRef = useRef<number | null>(null);
const isMountedRef = useRef(true);
useEffect(() => {
isMountedRef.current = true;
if (!token) {
if (wsRef.current) {
wsRef.current.close(1000, "Token missing - closing");
wsRef.current = null;
}
setStatus("idle");
return;
}
const fullUrl = `wss://${API_URL}/ws/${url}/?token=${token}`;
function connect() {
if (!token || !isMountedRef.current) return;
setStatus("connecting");
const ws = new WebSocket(fullUrl);
wsRef.current = ws;
ws.onopen = () => {
if (!isMountedRef.current) return;
setStatus("open");
retryDelayRef.current = 1000;
};
ws.onmessage = (ev) => {
if (!isMountedRef.current) return;
try {
const parsed: WSMessage = JSON.parse(ev.data);
onMessage(parsed);
} catch (err) {
console.error("Failed to parse WS message:", err, ev.data);
}
};
// onerror + onclose: Lessons 19–20
}
connect();
return () => {
/* Lesson 20 */
};
}, [url, token]);
return { status };
}The effect depends on [url, token] only. Changing room or JWT tears down the old socket and opens a new one. Missing NEXT_PUBLIC_API_URL produces a nonsense wss://undefined/ws/... — fail fast in dev if it is unset.
send behind a ref that no-ops unless status === "open", or you will fight StrictMode double-connects.useWebSocket("dashboard", token, console.log). Log status as you pass a real token, then null. Confirm the socket appears and disappears in DevTools.19Exponential backoff capped at 30s, and do not reconnect after logout
close, if a token still exists and the component is mounted, wait retryDelayRef (1s → 2s → … → 30s) and call connect again. Opening resets the delay to 1s. Logout must not schedule a retry.onclose. Copy it exactly before you “improve” it. Capture delay, double-and-cap *after*, schedule with the captured value. That matches the repo and is easy to test with fake timers.ws.onerror = (e) => {
console.error("WebSocket error:", e);
};
ws.onclose = () => {
if (!isMountedRef.current) return;
setStatus("closed");
wsRef.current = null;
// If user logged out → do NOT reconnect
if (!token) return;
const delay = retryDelayRef.current;
retryDelayRef.current = Math.min(delay * 2, 30_000);
reconnectTimerRef.current = window.setTimeout(connect, delay);
};token inside onclose is the value from the effect closure. When the user logs out, React re-runs the effect with token === null, cleanup closes the socket, and the new effect body hits the “Token missing” branch. The if (!token) return is defense in depth if onclose races cleanup.
Reset retryDelayRef.current = 1000 in onopen *and* in the effect cleanup. Otherwise a flaky room change inherits a 30s wait.
onerror *and* onclose. Browsers fire both; you would stack two timers.connecting → closed → connecting and measure gaps: ~1s, 2s, 4s, up to 30s. Then set token to null mid-retry and confirm the timer is cleared (Lesson 20).20beforeunload, pagehide, and isMountedRef
beforeunload and pagehide. Both call close(1000, "Tab closed or refreshed") and null wsRef. Safari and mobile often skip beforeunload but fire pagehide when the page is frozen or discarded. Without this, the server waits for ping timeout and the user count stays wrong.useEffect(() => {
function handleTabClose() {
if (wsRef.current) {
wsRef.current.close(1000, "Tab closed or refreshed");
wsRef.current = null;
}
}
window.addEventListener("beforeunload", handleTabClose);
window.addEventListener("pagehide", handleTabClose);
return () => {
window.removeEventListener("beforeunload", handleTabClose);
window.removeEventListener("pagehide", handleTabClose);
};
}, []);The connect effect’s cleanup is the other half: isMountedRef.current = false, clearTimeout(reconnectTimerRef), close(1000, "Component unmounted"), setStatus("idle"), reset delay to 1000. Every handler on the socket starts with if (!isMountedRef.current) return so a late onmessage cannot setStatus on an unmounted tree.
isMountedRef starts true. Cleanup sets false. The next effect run sets true again at the top. That pairing is what makes StrictMode (Lesson 22) safe.
setStatus in cleanup is legal in React 18+ for this pattern but unnecessary if the component is gone. The repo still sets "idle" so a fast remount does not flash "open".console.log in handleTabClose and in cleanup. Refresh the page (expect pagehide/beforeunload). Navigate away in the App Router (expect cleanup, not always beforeunload).21Shared socket via Context and a subscription registry
WebSocket and dispatch by msg.type / channel through a registry.useWebSocket2 is safe when one layout calls it. If twelve cards each call it with the same url and token, you open twelve upgrades, twelve backoffs, and twelve heartbeats. Lift the socket to a provider. Widgets register callbacks; the provider’s onMessage fans out."use client";
import { createContext, useContext, useEffect, useRef, type ReactNode } from "react";
import { useWebSocket } from "@/hooks/useWebSocket2";
type Handler = (msg: { type?: string; data?: unknown }) => void;
const SocketCtx = createContext<{
status: "idle" | "connecting" | "open" | "closed";
subscribe: (type: string, handler: Handler) => () => void;
} | null>(null);
export function SocketProvider({
token,
children,
}: {
token: string | null;
children: ReactNode;
}) {
const registry = useRef(new Map<string, Set<Handler>>());
const { status } = useWebSocket("dashboard", token, (msg) => {
const set = registry.current.get(msg.type ?? "*");
set?.forEach((fn) => fn(msg));
registry.current.get("*")?.forEach((fn) => fn(msg));
});
function subscribe(type: string, handler: Handler) {
const set = registry.current.get(type) ?? new Set<Handler>();
set.add(handler);
registry.current.set(type, set);
return () => {
set.delete(handler);
};
}
return <SocketCtx.Provider value={{ status, subscribe }}>{children}</SocketCtx.Provider>;
}
export function useSocketEvent(type: string, handler: Handler) {
const ctx = useContext(SocketCtx);
if (!ctx) throw new Error("useSocketEvent outside SocketProvider");
const handlerRef = useRef(handler);
handlerRef.current = handler;
useEffect(() => ctx.subscribe(type, (msg) => handlerRef.current(msg)), [ctx, type]);
return ctx.status;
}The registry is a Map<string, Set<Handler>> so two widgets can listen to presence. Unsubscribe on unmount or you leak handlers and set state on dead cards. Resubscribe-on-open (Lesson 14) still happens once, inside the provider’s hook, not per widget.
SocketProvider in a client layout, not in each page, or App Router navigations will tear the socket down and replay backoff.useSocketEvent("tick", ...). Confirm DevTools shows one WS connection. Unmount one child and confirm the other still receives ticks.22StrictMode, stale closures, and why onMessage is not a dependency
onMessage that changes every render, a naive [url, token, onMessage] effect reconnects forever. This repo omits onMessage from the dependency array — which creates a stale-closure bug unless you add a ref.isMountedRef = false, close(1000, "Component unmounted")). The remount sets isMountedRef = true and connects again. That is correct. What is *incorrect* is putting an inline onMessage in the dependency list:// Parent re-renders often
useWebSocket("dashboard", token, (msg) => setTicks((n) => n + 1));That callback is a new function every render. If it were a dep, you would close and reopen the socket on every tick — a reconnect storm. useWebSocket2.ts uses [url, token] only and calls onMessage from the closure created when url/token last changed. After that, the socket talks to the first callback. State setters inside it may be stale, or you may log into a dead closure.
const onMessageRef = useRef(onMessage);
onMessageRef.current = onMessage;
ws.onmessage = (ev) => {
if (!isMountedRef.current) return;
try {
onMessageRef.current(JSON.parse(ev.data));
} catch (err) {
console.error("Failed to parse WS message:", err, ev.data);
}
};Assign onMessageRef.current = onMessage during render (legal for refs). The socket always invokes the latest handler. Lesson 21’s handlerRef is the same pattern at the registry boundary.
Do not “fix” StrictMode by skipping cleanup. You need cleanup in production for route changes.
onMessage, do not add it — add the ref and a comment pointing at this lesson.renderId from the parent callback without a ref, then with onMessageRef. Change parent state that does *not* change url/token. Only the ref version sees the new renderId on the next WS message.socket.io-client
5 items23Fallbacks: Engine.IO starts on HTTP, then upgrades to WebSocket
socket.io-client is not a thin WebSocket wrapper. It speaks Engine.IO: long-polling first (by default), then an upgrade to WebSocket if the handshake allows it. That is why it still works on hostile proxies.io(url), the client opens an HTTP poll (/socket.io/?EIO=4&transport=polling), receives a session id (sid), then tries transport=websocket. If the upgrade fails, it stays on polling. You pay an extra round trip and a different URL shape than wss://host/ws/dashboard.import { io, type Socket } from "socket.io-client";
const socket: Socket = io("https://api.example.com", {
path: "/socket.io",
transports: ["websocket", "polling"], // try WS first if you control the proxy
auth: { token },
autoConnect: true,
});
socket.on("connect", () => {
console.log("id", socket.id, "ws?", socket.io.engine.transport.name);
});Native useWebSocket2 has no fallback: a blocked upgrade is error + close + backoff against the same wss URL forever. If your enterprise users sit behind proxies that strip Upgrade, socket.io (or your own long-poll fallback) is the product decision, not a style preference.
Force transports: ["websocket"] only when you have proven 101 works everywhere you ship. That removes the polling machinery but also removes the safety net.
socket.io. You should see a poll and then a WS. If you only see polls, the upgrade is failing — fix infra before blaming React.engine.transport.name on connect and upgrade. Then set transports: ["polling"] and confirm messages still flow, slower.24Rooms: fan-out without inventing a registry on the server
join/leave changes membership; to(room).emit fans out. This is the server analog of Lesson 21’s client registry.join (or the server joins you from JWT claims). Everyone in shift:42 receives attendance:update. One socket can sit in many rooms. Rooms are in-memory per Node process unless you add Redis (Lesson 31).// Client
socket.emit("join", { room: "shift:42" });
socket.on("attendance:update", (row) => {
upsertRow(row);
});
// Server (Node) — conceptual
io.on("connection", (socket) => {
socket.on("join", ({ room }: { room: string }) => {
void socket.join(room);
});
socket.on("attendance:ping", (row) => {
socket.to(row.room).emit("attendance:update", row);
});
});Native WebSocket needs the same design — you just write subscribe frames and a Map<room, Set<ws>> yourself. socket.io’s rooms are why teams adopt it for chat. They are also why serverless is a poor host: rooms die when the isolate dies.
join on the server using the same JWT you used to connect. Never trust the client’s room name alone.25Acknowledgements, reconnect, and namespaces
/chat vs /admin). Reconnect is built in — you still must resubscribe rooms that are not auto-joined on connect.{ id, type: "ack" } (Lesson 16). socket.io lets you pass a function as the last argument to emit. The server calls it with a payload. Timeouts are supported so a hung ack becomes an error.socket.emit("chat:send", { room: "r1", body: "hello" }, (res: { ok: boolean; id: string }) => {
if (!res.ok) markFailed();
else markDelivered(res.id);
});
socket.timeout(5_000).emit("chat:send", payload, (err: Error | null, res?: { id: string }) => {
if (err) markFailed();
else if (res) markDelivered(res.id);
});
const admin = io("https://api.example.com/admin", { auth: { token } });
socket.on("connect", () => {
socket.emit("join", { room: "shift:42" }); // rooms do not survive reconnect unless you redo this
});socket.io-client reconnects with its own backoff (reconnectionAttempts, reconnectionDelayMax). That overlaps useWebSocket2 — do not wrap socket.io in that hook or you will double-retry. Listen to reconnect / connect to flush queues and re-join rooms. Namespaces (io("/admin")) are not rooms; they can have different middleware and event names.
timeout(1000) path runs.26Auth on socket.io and what it costs in the bundle
auth / extraHeaders (Node) / cookies over copying ?token= from the native hook. You pay for that convenience with Engine.IO + socket.io parser code in the client bundle.auth as a payload during the Engine.IO handshake (not as an arbitrary browser header — browsers still cannot set Authorization on the WS upgrade). On Node you *can* set extraHeaders. Cookies work like native WS.const socket = io(process.env.NEXT_PUBLIC_API_URL!, {
auth: { token },
withCredentials: true, // cookies
reconnection: true,
reconnectionAttempts: Infinity,
reconnectionDelay: 1_000,
reconnectionDelayMax: 30_000,
});
socket.on("connect_error", (err) => {
if (err.message === "unauthorized") socket.disconnect();
});Bundle: a minimal native hook is a few kilobytes of *your* code. socket.io-client is tens of KB gzipped depending on version and tree-shaking. For a Next.js dashboard that already ships React, that may be fine. For a marketing page that needs one notification stream, SSE or native WS is the smaller choice.
Do not import socket.io from a Server Component. Same rule as useWebSocket2: client only.
import("socket.io-client") inside the provider if only one route needs it. That keeps the home page’s JS smaller.@next/bundle-analyzer once with a page that imports socket.io-client and once with only useWebSocket2. Record the delta on that route.27Native WebSocket vs socket.io — comparison table
| Concern | Native useWebSocket2 | socket.io-client |
|---|---|---|
| Browser API | WebSocket | Engine.IO + extra protocol |
| Fallback if WS blocked | None (backoff on the same wss) | HTTP long-polling |
| Reconnect | You (1s → 30s, no jitter in this repo) | Built-in, configurable |
| Rooms / namespaces | DIY frames | Built-in |
| Acks | DIY seq | emit(..., ack) |
| Auth | Query token in this repo | auth, cookies, headers (Node) |
| Heartbeat | Server ping or DIY | Engine.IO ping/pong |
| Bundle | ~your hook | Library weight |
| Next.js serverless host | Still need a long-lived WS process | Same — plus sticky/Redis for rooms |
| Debug | DevTools WS frames are JSON you invented | Engine.IO packets, then your events |
function chooseClient(opts: { hostileProxies: boolean; needRooms: boolean }): "native" | "io" {
if (opts.hostileProxies || opts.needRooms) return "io";
return "native";
}TimeLens chose native + JWT query + 30s cap because the backend already spoke a JSON protocol and the audience is employees on modern browsers. That is a valid production choice — as long as someone owns Lessons 12–17.
Server-Sent Events
2 items28EventSource and Last-Event-ID
EventSource is the browser’s native SSE client. It auto-reconnects and automatically sends the last id: it saw as Last-Event-ID, so the server can resume the stream.text/event-stream: fields id, event, data, and optional retry (milliseconds). Multiple data: lines join with \n. A blank line flushes one event. If you omit id:, resume cannot work and the client reconnects from “now.”const source = new EventSource("/api/jobs/42/stream");
source.onopen = () => console.log("SSE open", source.readyState); // 1 = OPEN
source.onerror = () => console.log("SSE error/retry", source.readyState); // 0 CONNECTING or 2 CLOSED
source.addEventListener("token", (ev: MessageEvent<string>) => {
appendChat(ev.data);
// ev.lastEventId is the last id: from the wire
});
source.addEventListener("done", () => {
source.close(); // stop auto-reconnect
});// Server-shaped payload the browser parses for you
// id: 17
// event: token
// data: {"text":"Hello"}
//
// id: 18
// event: done
// data: {}Unlike useWebSocket2, you do not write backoff. The browser uses retry: or a default. You *do* still close() on unmount or the stream continues in the background. EventSource.readyState is 0/1/2 — no CLOSING.
id: on job streams. Support tickets that say “the answer restarted from the beginning on flaky wifi” are missing Last-Event-ID.29EventSource cannot set custom headers — use a fetch stream
new EventSource(url) cannot attach Authorization. If your API requires a header (not a cookie), either put a short-lived token in the query (same tradeoff as Lesson 13) or parse SSE yourself from fetch.fetch the stream and read response.body with a TextDecoder. You then own reconnect, Last-Event-ID, and abort.async function subscribeSse(
url: string,
token: string,
onEvent: (event: string, data: string) => void,
signal: AbortSignal,
) {
let lastId = "";
while (!signal.aborted) {
const res = await fetch(url, {
headers: {
Authorization: `Bearer ${token}`,
Accept: "text/event-stream",
...(lastId ? { "Last-Event-ID": lastId } : {}),
},
signal,
});
if (!res.ok || !res.body) throw new Error(`SSE HTTP ${res.status}`);
const reader = res.body.getReader();
const decoder = new TextDecoder();
let buf = "";
while (true) {
const { value, done } = await reader.read();
if (done) break;
buf += decoder.decode(value, { stream: true });
const chunks = buf.split("\n\n");
buf = chunks.pop() ?? "";
for (const raw of chunks) {
const fields = Object.fromEntries(
raw
.split("\n")
.map((line) => {
const i = line.indexOf(":");
return [line.slice(0, i), line.slice(i + 1).trimStart()] as const;
}),
);
if (fields.id) lastId = fields.id;
if (fields.data) onEvent(fields.event ?? "message", fields.data);
}
}
}
}Abort the reader in useEffect cleanup (AbortController) the same way isMountedRef guards the WS hook. Do not parse SSE in a Server Component and expect the browser to stay connected — the HTTP response would have to be the streamed body of the RSC request, which is the wrong lifetime.
EventSource (auto-retry, less code). Use fetch-stream when the API is a third-party bearer-only host.Authorization. Confirm EventSource gets 401. Switch to the fetch loop and confirm events parse. Unmount and assert the network request shows canceled.Next.js
2 items30App Router cannot hold sockets — run a separate WebSocket server
useWebSocket2 runs in the browser. NEXT_PUBLIC_API_URL points at that process, not at /app/api/ws/route.ts on Vercel. A Route Handler can *upgrade* only if you are on a Node server that supports it (custom server, or a platform that exposes raw sockets). On default serverless, the isolate is gone after the response — there is nothing left to hold the connection.// app/dashboard/live/page.tsx — Server Component (no socket)
import { LiveAgents } from "./live-agents";
export default function Page() {
return <LiveAgents />;
}
// live-agents.tsx
"use client";
import { useWebSocket } from "@/hooks/useWebSocket2";
export function LiveAgents() {
const token = useAuthToken(); // client-visible access token or a short WS ticket
const { status } = useWebSocket("agents", token, (msg) => {
if (msg.type === "agent") mergeAgent(msg.data);
});
return <p>socket {status}</p>;
}The WS server can be Django Channels, a Node ws process, socket.io on Fastify, or a managed product (Ably, Pusher, PartyKit). The Next.js app still owns auth pages, RSC data, and the hook. Issue a short-lived WS ticket from a Route Handler if you do not want the long-lived access token in the query string (Lesson 13).
ws or socket.io into a file that also exports a Server Component without isolating the import behind import "server-only" *and* a real long-lived host. The import is not the feature — the process lifetime is.vercel.app/api. If your diagram arrows into a Route Handler on serverless, redraw it.31Serverless, edge, idle timeouts, sticky sessions, Redis adapter
proxy_read_timeout, AWS ALB idle timeout (~60s default), and Cloudflare proxy settings will emit 1006 if no frames (including pings) cross the wire. Raise timeouts on the WS path only, and ping under that budget (Lesson 10).// Conceptual multi-instance fan-out — not in the Next.js repo
import { Server } from "socket.io";
import { createAdapter } from "@socket.io/redis-adapter";
import { createClient } from "redis";
const io = new Server(httpServer, {
cors: { origin: process.env.WEB_ORIGIN, credentials: true },
pingInterval: 20_000,
pingTimeout: 20_000,
});
const pub = createClient({ url: process.env.REDIS_URL });
const sub = pub.duplicate();
await Promise.all([pub.connect(), sub.connect()]);
io.adapter(createAdapter(pub, sub));Sticky sessions (load balancer cookie / IP hash) send the same client to the same instance so Engine.IO’s poll+upgrade handshake stays coherent. The Redis adapter publishes events to every instance so io.to("shift:42").emit reaches sockets that live elsewhere. Native WS needs the same idea: publish to Redis, each process writes to its local Set<WebSocket>.
Without Redis, “it works on one dyno” and fails at two. Without sticky sessions, socket.io polling upgrades 400. Without ping, “random disconnects at 60s.”
Testing
1 item32mock-socket, DevTools frames, wscat, and fake timers
WebSocket, watch real frames in DevTools, poke the server with wscat, and drive backoff with Jest fake timers. Do not require a staging cluster to assert status transitions.mock-socket (or a tiny class FakeWebSocket) lets you emit("open"), emit("message", data), and emit("close", { code }) from the test. Assert setStatus / onMessage / close reasons. This repo’s hook is awkward to test only because onMessage is not a ref and new WebSocket is implicit — inject a factory or mock globalThis.WebSocket.import { act, renderHook } from "@testing-library/react";
import { useWebSocket } from "@/hooks/useWebSocket2";
class FakeWebSocket {
static instances: FakeWebSocket[] = [];
readyState = 0;
onopen: (() => void) | null = null;
onmessage: ((ev: { data: string }) => void) | null = null;
onerror: ((e: unknown) => void) | null = null;
onclose: ((ev: { code: number; reason: string }) => void) | null = null;
url: string;
constructor(url: string) {
this.url = url;
FakeWebSocket.instances.push(this);
}
close = jest.fn();
send = jest.fn();
}
jest.useFakeTimers();
globalThis.WebSocket = FakeWebSocket as unknown as typeof WebSocket;
const onMessage = jest.fn();
const { result, unmount } = renderHook(() => useWebSocket("agents", "jwt", onMessage));
const ws = FakeWebSocket.instances.at(-1)!;
act(() => {
ws.readyState = 1;
ws.onopen?.();
});
expect(result.current.status).toBe("open");
act(() => {
ws.onmessage?.({ data: JSON.stringify({ type: "ping" }) });
});
expect(onMessage).toHaveBeenCalledWith({ type: "ping" });
act(() => {
ws.readyState = 3;
ws.onclose?.({ code: 1006, reason: "" });
});
act(() => {
jest.advanceTimersByTime(1_000);
});
expect(FakeWebSocket.instances.length).toBe(2);
unmount();DevTools: Network → WS → Messages shows each frame. Use this to verify resubscribe and to catch double connections from StrictMode. `npx wscat -c "wss://host/ws/agents/?token=..."` is the server smoke test without React. Fake timers prove 1s / 2s / 4s / 30s without sleeping the suite.
close was called with 1000 and "Component unmounted" on unmount — that locks Lesson 20.token: null no second FakeWebSocket is constructed when you advanceTimersByTime(60_000).