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 - Socket factory, React hooks, event listeners, message queue, typing indicators, volatile events, namespace multiplexing
• examples/authentication.md - Token auth, cookie auth, token refresh, namespace auth, auth state machine
• examples/rooms.md - Room manager, room hooks, multi-room chat, namespace sockets, conditional namespace access
• reference.md - Decision frameworks, client options reference, checklists

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:

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 Example 1 for complete type definitions.

Pattern 2: Client Configuration

Token goes in auth object (never query string). Use named constants for all timing values. The timeout option controls the connection timeout (default 20000ms). For acknowledgment timeouts, use ackTimeout (v4.6.0+) or socket.timeout(ms).emitWithAck().

const RECONNECTION_DELAY_MS = 1000;
const MAX_RECONNECTION_ATTEMPTS = 10;
const CONNECTION_TIMEOUT_MS = 20000;

const socket: TypedSocket = io(url, {
  auth: { token }, // NOT in query string
  reconnectionAttempts: MAX_RECONNECTION_ATTEMPTS,
  reconnectionDelay: RECONNECTION_DELAY_MS,
  timeout: CONNECTION_TIMEOUT_MS, // Connection timeout
  transports: ["websocket", "polling"],
});

Key distinction: timeout = connection timeout. ackTimeout = per-emit acknowledgment timeout (requires retries option, v4.6.0+).

See examples/core.md Example 1 for full factory implementation.

Pattern 3: Connection Lifecycle

Socket-level events (connect, disconnect, connect_error) track the socket. Manager-level events (reconnect_attempt, reconnect, reconnect_failed) track the underlying connection. Always listen to both.

socket.on("connect", () => {
  /* connected */
});
socket.on("disconnect", (reason) => {
  // socket.active === true means it will reconnect
});
socket.on("connect_error", (error) => {
  /* handle */
});

// Manager-level: socket.io is the Manager instance
socket.io.on("reconnect_attempt", (attempt) => {
  /* show UI */
});
socket.io.on("reconnect_failed", () => {
  /* all attempts exhausted */
});

Critical: Check socket.recovered (v4.6.0+) after connect to determine if missed events were automatically delivered or if you need a full state refresh.

See examples/core.md Examples 2-3 for React hooks.

Pattern 4: Acknowledgments

Two approaches: automatic retries (v4.6.0+) or manual emitWithAck. Both confirm message delivery.

// Automatic retries (v4.6.0+)
const socket = io(url, { ackTimeout: 5000, retries: 3 });
socket.emit("message:send", content, (response) => {
  /* confirmed */
});

// Manual with emitWithAck
const response = await socket
  .timeout(5000)
  .emitWithAck("message:send", content);

Gotcha: