/web-realtime-socket-io

name: web-realtime-socket-io
description: Socket.IO v4.x client patterns, connection lifecycle, reconnection, authentication, rooms, namespaces, acknowledgments, binary data, TypeScript integration

Socket.IO Real-Time Communication Patterns

> **Quick Guide:** Socket.IO is a protocol layered over WebSocket, not an implementation of it — its client and a plain WebSocket server cannot talk to each other in either direction. What the layer buys is transport fallback, automatic reconnection, rooms, namespaces and acknowledgments, for about 14.5KB gzipped. The facts that change the answer: `auth` accepts a function that re-runs on every reconnection, `timeout` and `ackTimeout` are different clocks, and `socket.recovered` (v4.6.0+) tells you whether missed events were replayed or a full state refresh is owed.

**Detailed Resources:**

• [examples/core.md](examples/core.md) — typed socket factory, connection and event hooks, emit-with-ack, offline queue, volatile events, Manager multiplexing
• [examples/authentication.md](examples/authentication.md) — token auth, refresh on reconnect, per-namespace auth, cookie auth, auth state machine
• [examples/rooms.md](examples/rooms.md) — room manager and hooks, multi-room chat, namespace sockets, conditional namespace access
• [reference.md](reference.md) — client options, socket and manager events, disconnect reasons, comparison table, checklists

---

Which path applies

• **One connection to the default namespace** — `io(url, options)` creates the socket and its Manager together. This is the shape in [examples/core.md](examples/core.md) and covers most apps.
• **Several namespaces over one connection** — construct `new Manager(url)` yourself and call `manager.socket("/chat")` per namespace. The namespaces share a single transport and can each carry their own `auth`, which is what makes per-namespace authorization possible. See [examples/rooms.md](examples/rooms.md).

Calling `io()` more than once against the same URL opens a second transport rather than multiplexing — the Manager is what shares one.

---

<critical_requirements>

Before writing Socket.IO code

**Declare `ServerToClientEvents` and `ClientToServerEvents` and type the socket with them.** Event names are strings at runtime, so this is what turns `"mesage"` from a listener that never fires into a compile error.

**Pass tokens through the `auth` option.** They travel in the handshake rather than the URL, so they stay out of server logs, browser history and proxy logs — and the function form of `auth` is re-evaluated on every reconnection, which keeps a refreshed token from going stale.

**Remove every listener you add, with the same function reference.** `socket.off(event, handler)` in a `useEffect` cleanup is what stops handlers stacking up across re-renders and processing each message once per mount.

**Handle `connect_error` and the manager's `reconnect_failed`.** Between them they cover the two failures a user would otherwise experience as a screen that simply stopped updating.

**Check `socket.recovered` after `connect` (v4.6.0+).** It answers whether the server replayed what was missed or the client owes itself a full state refresh.

</critical_requirements>

---

**Auto-detection:** socket.io-client, io(), Manager, manager.socket(), socket.emit, socket.on, socket.off, emitWithAck, socket.timeout(), ackTimeout, socket.volatile, socket.recovered, socket.active, connect_error, reconnect_attempt, reconnect_failed, ServerToClientEvents, ClientToServerEvents, autoConnect, reconnectionDelayMax

**Applies to:**

• Bidirectional messaging where delivery confirmation matters
• Rooms and namespaces for targeted broadcast
• Reconnection with credential refresh and connection state recovery
• Restrictive networks that need a polling fallback
• Typed event contracts between client and server

**Handled elsewhere:**

• Where the token came from and how it is refreshed — the socket sends whatever `auth` yields.
• Where received data is stored and how it renders — a socket hook hands back messages and connection state, and nothing beyond that is its concern.
• The server's own room membership, namespace middleware and connection-state-recovery configuration; this skill covers the client half and names what it needs enabled server-side.
• A bidirectional channel without rooms, acknowledgments or fallback — that is the native WebSocket API underneath, which this protocol layer wraps rather than exposes.

---

<philosophy>

Socket.IO trades bundle size and protocol compatibility for four things that are otherwise hand-written: transport fallback, reconnection, server-side grouping and acknowledgments.

• **Transport is abstract.** The client opens with HTTP long-polling and upgrades to WebSocket once one is available, so a network that blocks the upgrade degrades instead of failing.
• **Rooms are a server concept.** A client asks to join and the server decides; the client is never told which rooms it is in.
• **Namespaces are protocol-level.** A client connects to `/chat` or `/admin` explicitly, each with its own middleware and its own `auth`, and all of them share one transport.
• **Connection state recovery (v4.6.0+)** replays events missed during a brief drop, within a server-configured window that defaults to two minutes.

CONNECTING -> CONNECTED <-> (events) -> DISCONNECTING -> DISCONNECTED
                 |                           |
             (error) <- reconnect <- (disconnect)

</philosophy>

---

<decision_framework>

Namespace or room

What is being separated?
  +-- A distinct feature area, with its own auth or middleware?
  |     -> namespace — the client connects to it, e.g. /chat, /admin
  +-- A set of users inside one feature, for targeted broadcast?
  |     -> room — server-side only, joined on request
  +-- Neither — one channel for everything?
        -> the default namespace "/"

How to authenticate

The `auth` option covers the token case,