/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:** Use Socket.IO for real-time bidirectional communication when you need rooms, namespaces, automatic reconnection, acknowledgments, or transport fallback. Socket.IO is NOT a WebSocket implementation - it adds a protocol layer with additional features. Always define typed event interfaces, use the `auth` option for tokens (never query strings), and clean up listeners on unmount.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST define typed interfaces for ALL Socket.IO events - ServerToClientEvents and ClientToServerEvents)**

**(You MUST use the `auth` option for authentication tokens - NEVER pass tokens in query strings)**

**(You MUST clean up event listeners on component unmount using socket.off())**

**(You MUST handle connection errors and implement proper reconnection state management)**

**(You MUST use named constants for all timeout values, retry limits, and intervals)**

</critical_requirements>

---

**Auto-detection:** Socket.IO, socket.io-client, io(), useSocket, socket.emit, socket.on, rooms, namespaces, acknowledgments, real-time

**When to use:**

• Building real-time features requiring rooms or namespaces (chat, multiplayer)
• Need automatic reconnection with connection state recovery
• Need acknowledgments/callbacks for message delivery confirmation
• Building applications that must work in restrictive network environments (fallback transports)
• Need server-side broadcasting patterns (emit to room, namespace, all clients)

**Key patterns covered:**

• TypeScript event interfaces (ServerToClientEvents, ClientToServerEvents)
• Client connection configuration and lifecycle
• Authentication via auth option and middleware
• Rooms and namespaces for logical grouping
• Acknowledgments and callbacks
• Connection state recovery (v4.6.0+)
• React integration hooks

**When NOT to use:**

• Simple WebSocket needs without rooms/namespaces (use native WebSocket)
• Need to connect to non-Socket.IO WebSocket servers (incompatible protocols)
• Minimal bundle size is critical (Socket.IO adds ~14.5KB gzipped overhead)

**Detailed Resources:**

• [examples/core.md](examples/core.md) - Socket factory, React hooks, event listeners, message queue, typing indicators, volatile events, namespace multiplexing
• [examples/authentication.md](examples/authentication.md) - Token auth, cookie auth, token refresh, namespace auth, auth state machine
• [examples/rooms.md](examples/rooms.md) - Room manager, room hooks, multi-room chat, namespace sockets, conditional namespace access
• [reference.md](reference.md) - Decision frameworks, client options reference, checklists

---

<philosophy>

Philosophy

Socket.IO provides a layer on top of WebSocket with additional features: automatic reconnection, room-based broadcasting, acknowledgments, and transport fallback. **It is NOT a WebSocket implementation** - a plain WebSocket client cannot connect to a Socket.IO server and vice versa.

**Key Architectural Concepts:**

1. **Transport Abstraction:** Socket.IO uses WebSocket when available but falls back to HTTP long-polling for restrictive networks. Default order: polling first, then upgrade to WebSocket.

2. **Rooms:** Server-side grouping mechanism for targeted broadcasting. Clients don't know about rooms - they're purely a server concept for organizing sockets.

3. **Namespaces:** Separate communication channels on the same connection. Used to separate concerns (e.g., `/chat`, `/admin`, `/notifications`). Each can have its own middleware.

4. **Connection State Recovery (v4.6.0+):** Missed events can be automatically delivered after brief disconnections, reducing manual state sync. Server-configurable with 2-minute default window.

**Connection Lifecycle:**

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

**Socket.IO vs Native WebSocket:**

| Feature | Socket.IO | Native WebSocket | | ------------------ | --------------------- | -------------------- | | Transport fallback | Automatic | Manual | | Reconnection | Built-in | Manual | | Rooms | Built-in | Manual (server-side) | | Namespaces | Built-in | Not available | | Acknowledgments | Built-in | Manual | | Protocol | Custom (incompatible) | Standard WebSocket | | Bundle size | ~14.5KB gzipped | Native (0KB) |

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: TypeScript Event Interfaces

Define separate interfaces for each communication direction. Socket.IO v4 enforces these at compile time.

interface ServerToClientEvents {
  "message:received": (message: ChatMessage) => void;
  "user:joined": (user: User) => void;
  error: (error: SocketError) => void;
}

interface ClientToServerEvents {
  "message:send": (
    content: string,
    callback: (res: MessageResponse) => void,
  ) => void;
  "room:join": (roomId: string, callback: (result: JoinResult) => void) => void;
}

type TypedSocket = Socket<ServerToClientEvents, ClientToServerEvents>;

**Why this matters:** Without typed events, typos in event names fail silently at runtime. Typed interfaces catch `"mesage"` vs `"message"` at compile time.

See [examples/core.md](examples/core.md) Example 1 for complete type definitions.

---

Pattern 2: Client Configuration

Token goes in `auth` object (never query string)