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.
// 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.
// 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.
Practice what you learned
1. Which call sends an event to every connected client except the sender?
2. What does the disconnect reason 'io server disconnect' mean for client-side auto-reconnect?
3. How do you broadcast a message to every socket in a specific room?
4. Why shouldn't you rely on socket.id as a stable user identifier?
5. What does connectionStateRecovery (v4.6+) help restore after a brief disconnect?
Was this page helpful?
You May Also Like
Socket.IO Best Practices
Practical patterns for structuring, scaling, and maintaining production Socket.IO applications.
Debugging Socket.IO
Tools and techniques for diagnosing connection failures, dropped events, and scaling bugs in Socket.IO apps.
Socket.IO Interview Questions
Common interview questions on Socket.IO internals, scaling, and design trade-offs, with model answers.
Related Reading
Related Study Notes in Programming
Browse all study notesApache Spark Study Notes
Programming · 30 topics
ProgrammingApache Flink Study Notes
Programming · 30 topics
ProgrammingHadoop Study Notes
Programming · 30 topics
ProgrammingSnowflake Study Notes
Programming · 30 topics
ProgrammingApache Airflow Study Notes
Programming · 30 topics
Programmingdbt (Data Build Tool) Study Notes
Programming · 30 topics