Socketio

---
name: socketio
description: "Socket.IO 4.x covering namespaces, rooms, acknowledgements, adapters, scaling, connection state recovery, middleware, TypeScript types, and multi-server deployment. Use for \"Socket.IO\", \"socket.io\", \"rooms\", \"namespaces\", \"Socket.IO adapter\", \"Redis adapter\", \"Socket.IO scaling\", \"Socket.IO middleware\", \"Socket.IO authentication\", \"Engine.IO\", \"Socket.IO reconnect\", \"emitWithAck\", \"Socket.IO admin\", \"connection state recovery\", \"volatile emit\", \"Socket.IO TypeScript\"."
license: MIT
---

# Socket.IO 4.x

This skill covers Socket.IO 4.x (latest stable: 4.8.x), the real-time communication library built on Engine.IO. Socket.IO is NOT a WebSocket wrapper -- it is a higher-level protocol with its own features. It has deep knowledge of:

- Engine.IO transport layer (HTTP long-polling upgrade to WebSocket)
- Namespaces (multiplexed communication channels)
- Rooms (server-side broadcast groups)
- Acknowledgements and `emitWithAck` (request/response pattern)
- Connection state recovery (v4.6+)
- Middleware system (connection, packet, namespace)
- Adapter system for multi-server scaling (Redis, Redis Streams, Postgres, MongoDB, Cluster)
- TypeScript event typing
- Admin UI for monitoring

## How to Approach Tasks

1. **Classify** the request:
   - **Architecture / core features** -- Load `references/architecture.md` for Engine.IO, namespaces, rooms, events, recovery
   - **Scaling / best practices** -- Load `references/best-practices.md` for adapters, sticky sessions, middleware, TypeScript, Admin UI
   - **Troubleshooting** -- Load `references/diagnostics.md` for connection issues, room broadcasting, adapter problems, performance
   - **Cross-technology comparison** -- Read the `overview` skill

2. **Gather context** -- Socket.IO version, runtime (Node.js, Deno, Bun), adapter in use, scaling approach, client platform

3. **Analyze** -- Apply Socket.IO-specific reasoning: namespace isolation, room lifecycle, adapter propagation, transport upgrade.

4. **Recommend** -- Provide server and client JavaScript/TypeScript code, adapter configuration, infrastructure setup.

## Core Architecture

### Engine.IO Transport Layer

Engine.IO always starts with HTTP long-polling, then upgrades to WebSocket. Heartbeat: server sends `ping` every 25s; client responds with `pong` within 20s.

### Key Distinction

Socket.IO requires matching client/server libraries. A raw WebSocket client cannot connect to a Socket.IO server.

### Namespaces

```javascript
const adminNsp = io.of("/admin");
adminNsp.on("connection", (socket) => { /* ... */ });
```

Each namespace has independent event handlers, rooms, and middleware.

### Rooms

Server-side only broadcast groups:
```javascript
socket.join("room1");
io.to("room1").emit("event", data);
socket.to("room1").emit("event", data); // excludes sender
```

### Acknowledgements

```javascript
const result = await socket.timeout(5000).emitWithAck("create:user", data);
```

### Connection State Recovery (v4.6+)

```javascript
const io = new Server(httpServer, {
  connectionStateRecovery: { maxDisconnectionDuration: 2 * 60 * 1000 }
});
```

Restores socket ID, rooms, and missed packets after brief disconnection.

## Anti-Patterns

1. **Using namespaces as rooms** -- They serve different purposes. Namespaces separate concerns; rooms group connections within a namespace.
2. **No sticky sessions with long-polling** -- Multi-server without sticky sessions causes HTTP 400 "Session ID unknown" errors.
3. **Not handling the non-recovered case** -- Connection state recovery can fail. Always implement the fallback path.
4. **Forgetting `next()` in middleware** -- Connection hangs until timeout if `next()` is not called.
5. **Creating too many static namespaces** -- Use dynamic namespaces for per-entity isolation.
6. **Not accessing `socket.rooms` in `disconnecting` event** -- In `disconnect` event, `socket.rooms` is already empty. Use `disconnecting` to read rooms before cleanup.
7. **Using `forceNew: true` unnecessarily** -- Disables multiplexing, creating separate WebSocket connections per namespace.
8. **No adapter for multi-server** -- Without an adapter, broadcasts only reach clients on the local server.

## Reference Files

- `references/architecture.md` -- Engine.IO transport, namespaces, rooms, events, acknowledgements, binary, connection state recovery, middleware
- `references/best-practices.md` -- Adapter selection, scaling patterns, sticky sessions, TypeScript typing, Admin UI, room management patterns, authentication
- `references/diagnostics.md` -- Connection failures, room broadcast issues, adapter problems, sticky session errors, performance, upgrade issues

## Cross-References

- `overview` skill -- Socket.IO vs SignalR, WebSocket, SSE comparisons
- `websocket` skill -- Raw WebSocket protocol (Socket.IO builds on top)