Socket.IO Quick Reference

Analogy categoryAnalogies

Core Server and Client APIs

The essential server-side surface is small: io.on('connection', socket => ...) fires per new client, socket.emit() sends to just that client, socket.broadcast.emit() sends to everyone except the sender, and io.emit() sends to every connected client across all namespaces of the default namespace. On the client, io(url, options) opens a connection, socket.on(event, handler) subscribes, socket.emit(event, data, ackCallback) sends with an optional acknowledgement, and socket.disconnect() closes the connection manually — memorizing this small vocabulary covers the majority of day-to-day Socket.IO code.

🏏

Cricket analogy: socket.emit() is like a captain giving instructions to one specific fielder, while io.emit() is like the umpire making an announcement heard by every player and spectator in the stadium at once.

javascript

// server
const { Server } = require('socket.io');
const io = new Server(httpServer, { cors: { origin: 'https://app.example.com' } });

io.on('connection', (socket) => {
  socket.emit('welcome', { id: socket.id });          // to this client only
  socket.broadcast.emit('userJoined', socket.id);      // to everyone else
  io.emit('onlineCount', io.engine.clientsCount);       // to everyone

  socket.on('disconnect', (reason) => {
    console.log(socket.id, 'left:', reason);
  });
});

// client
import { io } from 'socket.io-client';
const socket = io('https://api.example.com', { auth: { token } });
socket.on('connect', () => console.log('connected', socket.id));
socket.emit('ping', { t: Date.now() }, (ack) => console.log('ack', ack));

Rooms, Namespaces, and Common Config Options

socket.join(room) and socket.leave(room) manage room membership, io.to(room).emit() (or the alias io.in(room).emit()) broadcasts to everyone in a room, and io.of('/namespace') creates an isolated namespace with its own connection handler and middleware. Key constructor options to remember: cors for cross-origin access control, pingInterval/pingTimeout for heartbeat tuning, maxHttpBufferSize for payload size limits, and connectionStateRecovery (Socket.IO v4.6+) to automatically restore a client's rooms and missed events after a brief disconnect.

🏏

Cricket analogy: socket.join(room) is like a player being added to a specific squad list for an upcoming match, while io.to(room).emit() is the team manager's message reaching only that squad.

javascript

// rooms
socket.join('room:42');
io.to('room:42').emit('update', payload);
socket.leave('room:42');

// namespace
const adminNsp = io.of('/admin');
adminNsp.use(adminAuthMiddleware);
adminNsp.on('connection', (socket) => { /* ... */ });

// key config options
const io = new Server(httpServer, {
  cors: { origin: ['https://app.example.com'], credentials: true },
  pingInterval: 25000,
  pingTimeout: 20000,
  maxHttpBufferSize: 1e6,
  connectionStateRecovery: { maxDisconnectionDuration: 2 * 60 * 1000 },
});

socket.id is regenerated on every reconnect by default. If you need a stable per-user identifier across reconnects, store your own user ID in socket.data during authentication rather than relying on socket.id.

Disconnect Reasons and Client Options Cheat Sheet

The disconnect event's reason string tells you who initiated the close: 'io server disconnect' means the server called socket.disconnect() and the client will NOT auto-reconnect, 'io client disconnect' means the client called it locally, 'ping timeout' means no heartbeat response arrived in time, and 'transport close'/'transport error' indicate the underlying connection dropped (e.g., network loss). On the client constructor, reconnection: true (default), reconnectionAttempts, reconnectionDelay, and reconnectionDelayMax control retry behavior, while autoConnect: false lets you defer calling socket.connect() until you're ready (e.g., after fetching an auth token).

🏏

Cricket analogy: 'io server disconnect' is like the umpire calling off play and sending everyone home — no auto-restart happens, unlike a rain delay ('transport close') where play is expected to resume once conditions clear.

When the server explicitly calls socket.disconnect(), the client's automatic reconnection logic does NOT kick in (reason: 'io server disconnect') — you must call socket.connect() manually if you want to retry in that case.

socket.emit() targets one client; socket.broadcast.emit() targets all but the sender; io.emit() targets everyone.
socket.join()/leave() manage room membership; io.to(room).emit() broadcasts to a room.
io.of('/name') creates an isolated namespace with its own middleware and connection handler.
Key config: cors, pingInterval/pingTimeout, maxHttpBufferSize, connectionStateRecovery.
disconnect reason strings ('io server disconnect', 'ping timeout', 'transport close') indicate the real cause.
'io server disconnect' disables client auto-reconnect; you must call socket.connect() manually to retry.
Use socket.data (not socket.id) to store a stable, server-verified user identity across reconnects.