Socket.IO — User Guide

1. Quick Start

Socket.IO is a real-time, bidirectional, event-based communication library for the web. It enables instant data exchange between a Node.js server and any connected client (browser, mobile app, IoT device, or another server). Socket.IO is NOT a plain WebSocket wrapper — it is a higher-level framework that uses WebSocket as one of its transports while adding a rich feature set on top.

Key Features

• Automatic transport negotiation — starts with HTTP long-polling, upgrades to WebSocket seamlessly. Falls back gracefully if WebSocket is blocked by proxies or firewalls.
• Automatic reconnection — clients reconnect with exponential backoff by default; no manual retry logic needed.
• Rooms — server-side grouping mechanism for broadcasting to subsets of clients (chat rooms, game lobbies, notification channels).
• Namespaces — multiplexing multiple logical connections over a single underlying transport (e.g., /chat and /admin on one socket).
• Broadcasting — emit to all clients, all clients in a room, or all clients except specific ones, with a fluent chainable API.
• Acknowledgements — request-response pattern built into emit; the receiver can call back with data.
• Binary support — send and receive Buffer, ArrayBuffer, Blob, and File objects natively; the parser handles serialization.
• Connection state recovery — after a brief disconnection, the server can restore room memberships and replay missed events automatically.

Prerequisites

• Node.js 16 or later (LTS recommended)
• npm 7+ or yarn 1.22+
• A modern browser (Chrome, Firefox, Safari, Edge) for client-side usage

Minimal Install

mkdir my-realtime-app && cd my-realtime-app
npm init -y
npm install socket.io socket.io-client

Minimal Example

Server (server.js):

const { Server } = require("socket.io");

const io = new Server(3000, {
  cors: { origin: "*" }
});

io.on("connection", (socket) => {
  console.log(`Client connected: ${socket.id}`);

  socket.on("hello", (msg) => {
    console.log(`Received: ${msg}`);
    socket.emit("hello", `Echo: ${msg}`);
  });

  socket.on("disconnect", (reason) => {
    console.log(`Client disconnected: ${reason}`);
  });
});

console.log("Socket.IO server listening on port 3000");

Client (client.js):

const { io } = require("socket.io-client");

const socket = io("http://localhost:3000");

socket.on("connect", () => {
  console.log(`Connected as ${socket.id}`);
  socket.emit("hello", "world");
});

socket.on("hello", (msg) => {
  console.log(`Server says: ${msg}`);
});

Run it:

node server.js &
node client.js

Expected output:

Socket.IO server listening on port 3000
Client connected: abc123XYZ
Connected as abc123XYZ
Received: world
Server says: Echo: world

Tip

You do not need to set up Express or any HTTP framework to get started. The Server constructor can create its own HTTP server internally when you pass a port number directly.

What to Try Next

After verifying the minimal example works, explore Section 4 (Core Usage) for rooms, namespaces, and broadcasting. Section 5 has 25+ task-oriented recipes covering chat apps, authentication, TypeScript, and more.

2. Installation

From npm (recommended)

Server:

npm install socket.io

Client (Node.js or bundler):

npm install socket.io-client

Both together (for full-stack projects):

npm install socket.io socket.io-client

Important

The server package (socket.io) and the client package (socket.io-client) are versioned independently but designed to work together within the same major version. Always use matching major versions (e.g., both v4.x). Mixing v3 server with v4 client will cause silent connection failures.

CDN for Browser Usage

For quick prototyping or static HTML pages, load the client from a CDN:

<script src="https://cdn.socket.io/4.8.1/socket.io.min.js"></script>
<script>
  const socket = io("http://localhost:3000");
  socket.on("connect", () => console.log("Connected!"));
</script>

Alternatively, when serveClient is enabled on the server (the default), the server itself serves the client bundle at the configured path:

<script src="/socket.io/socket.io.js"></script>

ES Module Import (Browser)

<script type="module">
  import { io } from "https://cdn.socket.io/4.8.1/socket.io.esm.min.js";
  const socket = io("http://localhost:3000");
</script>

From Source

git clone https://github.com/socketio/socket.io.git
cd socket.io
npm install
npm run build

The monorepo uses npm workspaces. Building from source compiles all 12 packages (server, client, engine.io, parsers, adapters, etc.).

System Requirements

Post-Install Verification

Server check:

const { Server } = require("socket.io");
console.log("socket.io loaded successfully");
const io = new Server();
console.log(`Server instance created, path: ${io.path()}`);
io.close();

Client check:

const { io } = require("socket.io-client");
console.log("socket.io-client loaded successfully");
const socket = io("http://localhost:1", { autoConnect: false });
console.log(`Socket created, connected: ${socket.connected}`);

Run each with node -e or as a script. If no errors appear, the packages are installed correctly.

3. Configuration

This section covers the user-facing configuration options you need for day-to-day development. For production tuning, adapter configuration, cluster setup, and security hardening, see the Admin Guide.

Server Options

When creating a Server instance, pass an options object as the second argument (or the only argument if not attaching to an existing HTTP server):

const { Server } = require("socket.io");

const io = new Server(httpServer, {
  path: "/socket.io",
  serveClient: true,
  connectTimeout: 45000,
  cors: {
    origin: "https://myapp.com",
    methods: ["GET", "POST"]
  }
});

Socket.IO Server Options:

Engine.IO Options (passed through to the transport layer):

Client Options

The client io() factory accepts a URL and an options object:

const { io } = require("socket.io-client");

const socket = io("https://myserver.com", {
  path: "/socket.io",
  reconnection: true,
  reconnectionAttempts: Infinity,
  reconnectionDelay: 1000,
  timeout: 20000,
  auth: { token: "my-jwt-token" }
});

Manager Options (connection-level):

Socket Options (passed alongside Manager options):

Matching Server and Client Configuration

The path option must be identical on both sides. If you change it on the server, change it on every client:

// Server
const io = new Server(httpServer, { path: "/my-custom-path" });

// Client
const socket = io("https://myserver.com", { path: "/my-custom-path" });

If they do not match, the client will receive 404 errors and never connect.

4. Core Usage

4.1 Connecting

Client-Side Connection

The io() function creates a socket connection:

const { io } = require("socket.io-client");

// Connect to the same host (browser) or specify URL (Node.js)
const socket = io("http://localhost:3000");

// Connect to a specific namespace
const adminSocket = io("http://localhost:3000/admin");

// Connect with options
const socket = io("http://localhost:3000", {
  auth: { token: "abc123" },
  transports: ["websocket"],
  autoConnect: false
});

// Manually connect when autoConnect is false
socket.connect();

Connection Events

socket.on("connect", () => {
  console.log("Connected:", socket.id);
});

socket.on("connect_error", (err) => {
  console.log("Connection error:", err.message);
});

socket.on("disconnect", (reason, details) => {
  console.log("Disconnected:", reason);
  // reason can be:
  //   "io server disconnect" — server called socket.disconnect()
  //   "io client disconnect" — client called socket.disconnect()
  //   "ping timeout" — server didn't respond in time
  //   "transport close" — connection was lost
  //   "transport error" — connection encountered an error
  //   "parse error" — received invalid packet
  //   "forced close" — client called manager.close()
});

Note

When the server forcefully disconnects a socket with socket.disconnect(true), the client receives "io server disconnect" and will NOT automatically reconnect. You must explicitly call socket.connect() if you want to reconnect.

Manager Events

The underlying Manager handles the transport connection and exposes its own events:

socket.io.on("open", () => console.log("Transport opened"));
socket.io.on("close", (reason) => console.log("Transport closed:", reason));
socket.io.on("ping", () => console.log("Ping from server"));
socket.io.on("reconnect", (attempt) => console.log(`Reconnected after ${attempt} attempts`));
socket.io.on("reconnect_attempt", (attempt) => console.log(`Reconnect attempt #${attempt}`));
socket.io.on("reconnect_error", (err) => console.log("Reconnect error:", err));
socket.io.on("reconnect_failed", () => console.log("Reconnect failed — gave up"));

Server-Side Connection Handling

io.on("connection", (socket) => {
  console.log("New client:", socket.id);
  console.log("Auth data:", socket.handshake.auth);
  console.log("Query params:", socket.handshake.query);
  console.log("Headers:", socket.handshake.headers);
  console.log("Remote address:", socket.handshake.address);

  socket.on("disconnect", (reason) => {
    console.log(`Client ${socket.id} disconnected: ${reason}`);
  });
});

4.2 Emitting Events

Socket.IO uses a publish-subscribe model. Any string can be an event name (except reserved names like connect, disconnect, error).

Basic Emit

// Client to server
socket.emit("chat message", "Hello, world!");

// Server to client
socket.emit("chat message", "Welcome!");

// Multiple arguments
socket.emit("user:update", { name: "Alice" }, [1, 2, 3], true);

Emit with Acknowledgement (Callback)

The sender passes a callback as the last argument. The receiver invokes it to send a response:

// Client sends, expects response
socket.emit("save:document", { title: "Draft" }, (response) => {
  console.log("Server acknowledged:", response);
});

// Server handles, responds
socket.on("save:document", (doc, callback) => {
  const savedId = saveToDb(doc);
  callback({ status: "ok", id: savedId });
});

Emit with Ack and Timeout

socket.timeout(5000).emit("save:document", { title: "Draft" }, (err, response) => {
  if (err) {
    console.log("Server did not acknowledge in time");
  } else {
    console.log("Saved:", response);
  }
});

Promise-Based Emit (emitWithAck)

// Client
try {
  const response = await socket.emitWithAck("save:document", { title: "Draft" });
  console.log("Response:", response);
} catch (err) {
  console.log("Timeout or error:", err);
}

// Server handler remains the same — just call the callback
socket.on("save:document", (doc, callback) => {
  callback({ status: "ok" });
});

Warning

When using emitWithAck, always set a timeout with socket.timeout(ms).emitWithAck(...). Without a timeout, the promise will hang forever if the other side never acknowledges. This was identified as a memory leak vector in production environments.

4.3 Listening for Events

Standard Listeners

// Listen for a specific event
socket.on("chat message", (msg) => {
  console.log("Message:", msg);
});

// Listen once (auto-removes after first call)
socket.once("welcome", (data) => {
  console.log("Welcome message:", data);
});

// Remove a specific listener
const handler = (msg) => console.log(msg);
socket.on("chat message", handler);
socket.off("chat message", handler);

// Remove all listeners for an event
socket.removeAllListeners("chat message");

Catch-All Listeners

// Listen to every incoming event
socket.onAny((eventName, ...args) => {
  console.log(`Event: ${eventName}`, args);
});

// Listen to every outgoing event
socket.onAnyOutgoing((eventName, ...args) => {
  console.log(`Sending: ${eventName}`, args);
});

// Remove catch-all listeners
socket.offAny();
socket.offAnyOutgoing();

Prepend Listeners

// Add listener to beginning of the listener array
socket.prependAny((eventName, ...args) => {
  console.log("First handler for any event:", eventName);
});

4.4 Rooms

Rooms are a server-side concept. They are arbitrary channels that sockets can join and leave. Rooms exist only on the server — clients do not know which rooms they are in.

Joining and Leaving

io.on("connection", (socket) => {
  // Join a room
  socket.join("room1");

  // Join multiple rooms
  socket.join(["room1", "room2", "room3"]);

  // Leave a room
  socket.leave("room1");

  // Every socket automatically joins a room named after its socket.id
  console.log(socket.rooms); // Set { socket.id, "room1", "room2", ... }
});

Broadcasting to Rooms

// Send to everyone in "room1" (including sender if in the room)
io.to("room1").emit("event", data);

// Same as to() — in() is an alias
io.in("room1").emit("event", data);

// Send to multiple rooms (union)
io.to("room1").to("room2").emit("event", data);

// Send to "room1" but exclude "room2"
io.to("room1").except("room2").emit("event", data);

// From within a socket handler: broadcast to room EXCLUDING the sender
socket.to("room1").emit("event", data);

Listing Sockets in a Room

// Get all socket IDs in a room
const sockets = await io.in("room1").fetchSockets();
for (const s of sockets) {
  console.log(s.id, s.data, s.rooms);
}

Bulk Room Operations

// Make all sockets in "room1" also join "room2"
io.in("room1").socketsJoin("room2");

// Make all sockets in "room1" leave "room2"
io.in("room1").socketsLeave("room2");

// Disconnect all sockets in "room1"
io.in("room1").disconnectSockets(true);

Tip

Use the socket's own ID as a "personal room" to send messages to a specific user. Every socket automatically joins a room matching its socket.id, so io.to(targetSocketId).emit("private", data) works out of the box. For persistent identity across reconnections, use a user-specific room (see Section 5 recipes).

4.5 Namespaces

Namespaces let you split your application logic over a single shared connection. They act as separate communication channels with their own events, rooms, and middleware.

Creating Namespaces (Server)

const { Server } = require("socket.io");
const io = new Server(3000);

// Main namespace (default)
io.on("connection", (socket) => {
  console.log("Main namespace:", socket.id);
});

// Custom namespace
const adminNsp = io.of("/admin");
adminNsp.on("connection", (socket) => {
  console.log("Admin namespace:", socket.id);
});

// Dynamic namespaces (regex)
const dynamicNsp = io.of(/^\/user-\w+$/);
dynamicNsp.on("connection", (socket) => {
  const namespace = socket.nsp.name; // e.g., "/user-alice"
  console.log(`Dynamic namespace ${namespace}:`, socket.id);
});

// Dynamic namespaces (function)
io.of((name, auth, next) => {
  // Validate and authorize
  if (name.startsWith("/project-")) {
    next(null, true);
  } else {
    next(new Error("Invalid namespace"));
  }
}).on("connection", (socket) => {
  console.log("Project namespace:", socket.nsp.name);
});

Connecting to Namespaces (Client)

// Default namespace
const socket = io("http://localhost:3000");

// Custom namespace
const adminSocket = io("http://localhost:3000/admin");

// Dynamic namespace
const userSocket = io("http://localhost:3000/user-alice");

When multiplexing is enabled (default), all namespace connections to the same server share a single underlying transport connection.

Namespace Middleware

adminNsp.use((socket, next) => {
  const token = socket.handshake.auth.token;
  if (isValidAdmin(token)) {
    next();
  } else {
    next(new Error("Unauthorized"));
  }
});

4.6 Broadcasting

The server provides a fluent, chainable API for targeting specific recipients.

Broadcast Targets

// To ALL connected clients (current namespace)
io.emit("announcement", "Server is restarting");

// To all EXCEPT the sender
socket.broadcast.emit("user:joined", socket.id);

// To a specific room
io.to("room1").emit("event", data);

// To multiple rooms (clients in room1 OR room2)
io.to("room1").to("room2").emit("event", data);

// Exclude specific rooms
io.except("room1").emit("event", data);
io.to("room2").except("room3").emit("event", data);

Broadcast Modifiers

// Volatile — drop the message if the client is not ready to receive
io.volatile.emit("cursor:move", { x: 100, y: 200 });

// With compression
io.compress(true).emit("large:data", bigPayload);

// Local — only broadcast to clients on THIS server (skip adapter broadcast in clusters)
io.local.emit("event", data);

// Timeout — expect acknowledgement from all recipients within a time window
io.timeout(5000).emit("important:event", data, (err, responses) => {
  if (err) {
    // Some clients did not acknowledge
  } else {
    // responses is an array of all acknowledgements
  }
});

Chain Everything Together

io.to("room1")
  .to("room2")
  .except("room3")
  .compress(true)
  .timeout(5000)
  .emit("complex:broadcast", data, (err, responses) => {
    console.log(`${responses.length} clients acknowledged`);
  });

emitWithAck for Broadcasts

try {
  const responses = await io.timeout(5000).emitWithAck("ping");
  console.log(`${responses.length} clients responded`);
} catch (err) {
  console.log("Some clients did not respond in time");
}

4.7 Binary Data

Socket.IO natively supports binary data. The parser automatically detects binary content and handles serialization.

// Server sends a Buffer
const buffer = Buffer.from("Hello binary world");
socket.emit("file:chunk", buffer);

// Client sends an ArrayBuffer (browser)
const arrayBuffer = new ArrayBuffer(8);
const view = new Uint8Array(arrayBuffer);
view.set([1, 2, 3, 4, 5, 6, 7, 8]);
socket.emit("binary:data", arrayBuffer);

// Mixed: object with binary inside
socket.emit("upload", {
  filename: "photo.jpg",
  mimetype: "image/jpeg",
  data: fileBuffer
});

// The parser handles nested binary in arrays and objects automatically
socket.emit("complex", {
  text: "metadata",
  files: [buffer1, buffer2],
  nested: { deep: { binary: buffer3 } }
});

Note

Binary payloads are extracted from the packet, sent as separate WebSocket frames, and reassembled on the receiving end. This is transparent to your code. The parser enforces attachment limits — if a packet claims more binary attachments than actually arrive, you will see a "too many attachments" parser error.

4.8 Error Handling

Client-Side Errors

// Connection error (failed to connect or lost during reconnection)
socket.on("connect_error", (err) => {
  console.error("Connection error:", err.message);
  // err.message contains the error reason
  // Common: CORS, auth failure, server down
});

// Disconnection
socket.on("disconnect", (reason) => {
  if (reason === "io server disconnect") {
    // The server explicitly disconnected this socket
    // Must manually reconnect
    socket.connect();
  }
  // Otherwise, the client will auto-reconnect
});

Server-Side Errors

io.on("connection", (socket) => {
  // Catch errors on individual sockets
  socket.on("error", (err) => {
    console.error(`Socket ${socket.id} error:`, err);
  });

  // Wrap event handlers with try/catch
  socket.on("risky:operation", async (data, callback) => {
    try {
      const result = await doSomethingRisky(data);
      callback({ status: "ok", result });
    } catch (err) {
      callback({ status: "error", message: err.message });
    }
  });
});

// Engine-level errors
io.engine.on("connection_error", (err) => {
  console.log("Engine error:", err.code, err.message, err.context);
});

Middleware Errors

When middleware calls next(err), the client receives a connect_error event:

// Server middleware
io.use((socket, next) => {
  const token = socket.handshake.auth.token;
  if (!token) {
    return next(new Error("Authentication required"));
  }
  next();
});

// Client handling
socket.on("connect_error", (err) => {
  console.log("Auth failed:", err.message); // "Authentication required"
});

5. Common Tasks

5.1 Chat Application

// Server
const { Server } = require("socket.io");
const io = new Server(3000, { cors: { origin: "*" } });

io.on("connection", (socket) => {
  socket.on("join room", (room) => {
    socket.join(room);
    socket.to(room).emit("system", `${socket.id} joined the room`);
  });

  socket.on("chat message", ({ room, message }) => {
    io.to(room).emit("chat message", {
      from: socket.id,
      message,
      timestamp: Date.now()
    });
  });

  socket.on("typing", (room) => {
    socket.to(room).emit("typing", socket.id);
  });

  socket.on("disconnect", () => {
    // Socket automatically leaves all rooms on disconnect
  });
});

// Client
const socket = io("http://localhost:3000");

socket.emit("join room", "general");

socket.on("chat message", ({ from, message, timestamp }) => {
  console.log(`[${new Date(timestamp).toLocaleTimeString()}] ${from}: ${message}`);
});

socket.on("system", (msg) => console.log(`*** ${msg} ***`));

socket.emit("chat message", { room: "general", message: "Hello everyone!" });

5.2 Real-Time Notifications

// Server — push notifications to specific users
const userSockets = new Map(); // userId -> Set<socketId>

io.on("connection", (socket) => {
  const userId = socket.handshake.auth.userId;
  socket.join(`user:${userId}`);

  if (!userSockets.has(userId)) userSockets.set(userId, new Set());
  userSockets.get(userId).add(socket.id);

  socket.on("disconnect", () => {
    userSockets.get(userId)?.delete(socket.id);
    if (userSockets.get(userId)?.size === 0) userSockets.delete(userId);
  });
});

// Called from your application logic (e.g., after a DB write)
function notifyUser(userId, notification) {
  io.to(`user:${userId}`).emit("notification", notification);
}

5.3 Room-Based Multiplayer Game

// Server
const games = new Map();

io.on("connection", (socket) => {
  socket.on("game:create", (gameId, callback) => {
    games.set(gameId, { players: [socket.id], state: {} });
    socket.join(`game:${gameId}`);
    callback({ status: "ok", gameId });
  });

  socket.on("game:join", (gameId, callback) => {
    const game = games.get(gameId);
    if (!game) return callback({ status: "error", message: "Game not found" });
    if (game.players.length >= 4) return callback({ status: "error", message: "Game full" });

    game.players.push(socket.id);
    socket.join(`game:${gameId}`);
    io.to(`game:${gameId}`).emit("game:player_joined", {
      playerId: socket.id,
      playerCount: game.players.length
    });
    callback({ status: "ok" });
  });

  socket.on("game:move", ({ gameId, move }) => {
    const game = games.get(gameId);
    if (!game) return;
    // Validate and apply move
    game.state = applyMove(game.state, move);
    io.to(`game:${gameId}`).emit("game:state", game.state);
  });

  socket.on("disconnect", () => {
    for (const [gameId, game] of games) {
      const idx = game.players.indexOf(socket.id);
      if (idx !== -1) {
        game.players.splice(idx, 1);
        io.to(`game:${gameId}`).emit("game:player_left", socket.id);
        if (game.players.length === 0) games.delete(gameId);
      }
    }
  });
});

5.4 Private Messaging

// Server — using user-specific rooms for persistence across reconnections
io.use((socket, next) => {
  const userId = socket.handshake.auth.userId;
  if (!userId) return next(new Error("userId required"));
  socket.data.userId = userId;
  next();
});

io.on("connection", (socket) => {
  // Join a personal room keyed by user ID (survives reconnection with new socket.id)
  socket.join(`user:${socket.data.userId}`);

  socket.on("private message", ({ to, content }) => {
    const message = {
      from: socket.data.userId,
      to,
      content,
      timestamp: Date.now()
    };
    // Send to recipient
    io.to(`user:${to}`).emit("private message", message);
    // Send back to sender (for multi-device sync)
    socket.emit("private message", message);
  });
});

5.5 File Upload Progress

// Client (browser)
async function uploadFile(file) {
  const chunkSize = 64 * 1024; // 64 KB chunks
  const totalChunks = Math.ceil(file.size / chunkSize);

  for (let i = 0; i < totalChunks; i++) {
    const start = i * chunkSize;
    const end = Math.min(start + chunkSize, file.size);
    const chunk = file.slice(start, end);
    const buffer = await chunk.arrayBuffer();

    await socket.timeout(10000).emitWithAck("file:chunk", {
      name: file.name,
      chunk: buffer,
      index: i,
      total: totalChunks
    });

    console.log(`Progress: ${Math.round(((i + 1) / totalChunks) * 100)}%`);
  }
}

// Server
const chunks = new Map();

io.on("connection", (socket) => {
  socket.on("file:chunk", ({ name, chunk, index, total }, callback) => {
    const key = `${socket.id}:${name}`;
    if (!chunks.has(key)) chunks.set(key, []);

    chunks.get(key)[index] = Buffer.from(chunk);

    if (chunks.get(key).filter(Boolean).length === total) {
      const fullFile = Buffer.concat(chunks.get(key));
      saveFile(name, fullFile);
      chunks.delete(key);
      callback({ status: "complete" });
    } else {
      callback({ status: "ok" });
    }
  });
});

5.6 Connection State Recovery

Connection state recovery allows the server to restore a client's room memberships and replay missed events after a brief disconnection, without any application-level logic.

// Server — enable connection state recovery
const io = new Server(3000, {
  connectionStateRecovery: {
    maxDisconnectionDuration: 2 * 60 * 1000, // 2 minutes (default)
    skipMiddlewares: true                      // skip auth on recovery (default)
  }
});

io.on("connection", (socket) => {
  if (socket.recovered) {
    // Connection was recovered — rooms are restored, missed events replayed
    console.log("Client recovered:", socket.id);
  } else {
    // Fresh connection — set up from scratch
    console.log("New client:", socket.id);
    socket.join("default-room");
  }
});

// Client — no special configuration needed, just handle reconnection
socket.on("connect", () => {
  if (socket.recovered) {
    console.log("Session recovered — rooms and missed events restored");
  } else {
    console.log("New session — re-subscribe to data");
  }
});

Important

Connection state recovery only works within the maxDisconnectionDuration window (default 2 minutes). After that, the server discards the recovery state. The feature relies on the in-memory adapter by default; for multi-server deployments, you need the cluster adapter.

5.7 Custom Parser

Socket.IO supports custom parsers for performance optimization or alternative serialization formats. The msgpack parser is a popular choice for reducing payload size.

// Install
// npm install @socket.io/msgpack-parser

// Server
const { Server } = require("socket.io");
const msgpackParser = require("@socket.io/msgpack-parser");

const io = new Server(3000, {
  parser: msgpackParser
});

// Client
const { io } = require("socket.io-client");
const msgpackParser = require("@socket.io/msgpack-parser");

const socket = io("http://localhost:3000", {
  parser: msgpackParser
});

Both server and client MUST use the same parser. Mismatched parsers will cause "parse error" disconnections.

5.8 TypeScript — Typed Events

Socket.IO has first-class TypeScript support with typed event maps:

// shared/types.ts — define event maps
interface ServerToClientEvents {
  "chat:message": (msg: { from: string; body: string; timestamp: number }) => void;
  "user:joined": (userId: string) => void;
  "user:left": (userId: string) => void;
}

interface ClientToServerEvents {
  "chat:send": (body: string, callback: (status: "ok" | "error") => void) => void;
  "room:join": (roomId: string) => void;
}

interface InterServerEvents {
  ping: () => void;
}

interface SocketData {
  userId: string;
  username: string;
}

// server.ts
import { Server } from "socket.io";

const io = new Server<
  ClientToServerEvents,
  ServerToClientEvents,
  InterServerEvents,
  SocketData
>(3000);

io.on("connection", (socket) => {
  // socket.data is typed as SocketData
  socket.data.userId = "abc";

  // Event handlers are fully typed
  socket.on("chat:send", (body, callback) => {
    io.emit("chat:message", {
      from: socket.data.userId,
      body,
      timestamp: Date.now()
    });
    callback("ok");
  });

  // TypeScript errors if you emit an undefined event or wrong argument types
  // socket.emit("nonexistent", 123); // TS error!
});

// client.ts
import { io, Socket } from "socket.io-client";

const socket: Socket<ServerToClientEvents, ClientToServerEvents> = io("http://localhost:3000");

socket.on("chat:message", (msg) => {
  // msg is typed as { from: string; body: string; timestamp: number }
  console.log(`${msg.from}: ${msg.body}`);
});

socket.emit("chat:send", "Hello!", (status) => {
  // status is typed as "ok" | "error"
  console.log(status);
});

5.9 Using with Express

const express = require("express");
const { createServer } = require("http");
const { Server } = require("socket.io");

const app = express();
const httpServer = createServer(app);
const io = new Server(httpServer, {
  cors: { origin: "*" }
});

// Express routes
app.get("/", (req, res) => {
  res.sendFile(__dirname + "/index.html");
});

// Socket.IO events
io.on("connection", (socket) => {
  console.log("Client connected");
});

// IMPORTANT: call httpServer.listen(), NOT app.listen()
httpServer.listen(3000, () => {
  console.log("Server running on port 3000");
});

5.10 Using with Koa

const Koa = require("koa");
const { createServer } = require("http");
const { Server } = require("socket.io");

const app = new Koa();
const httpServer = createServer(app.callback());
const io = new Server(httpServer);

io.on("connection", (socket) => {
  console.log("Client connected");
});

httpServer.listen(3000);

5.11 Using with NestJS

The Socket.IO monorepo includes a NestJS example. The pattern uses NestJS WebSocket gateways:

import {
  WebSocketGateway,
  WebSocketServer,
  SubscribeMessage,
  OnGatewayConnection,
  OnGatewayDisconnect
} from "@nestjs/websockets";
import { Server, Socket } from "socket.io";

@WebSocketGateway({ cors: { origin: "*" } })
export class ChatGateway implements OnGatewayConnection, OnGatewayDisconnect {
  @WebSocketServer()
  server: Server;

  handleConnection(client: Socket) {
    console.log("Client connected:", client.id);
  }

  handleDisconnect(client: Socket) {
    console.log("Client disconnected:", client.id);
  }

  @SubscribeMessage("message")
  handleMessage(client: Socket, payload: string): void {
    this.server.emit("message", payload);
  }
}

5.12 Authentication with Middleware

const jwt = require("jsonwebtoken");

// Server-side middleware
io.use((socket, next) => {
  const token = socket.handshake.auth.token;
  if (!token) {
    return next(new Error("Authentication required"));
  }

  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET);
    socket.data.user = decoded;
    next();
  } catch (err) {
    next(new Error("Invalid token"));
  }
});

io.on("connection", (socket) => {
  console.log("Authenticated user:", socket.data.user.name);
});

// Client-side
const socket = io("http://localhost:3000", {
  auth: {
    token: localStorage.getItem("jwt")
  }
});

socket.on("connect_error", (err) => {
  if (err.message === "Authentication required" || err.message === "Invalid token") {
    // Redirect to login
    window.location.href = "/login";
  }
});

For dynamic tokens that may refresh between reconnection attempts, pass a function:

const socket = io("http://localhost:3000", {
  auth: (cb) => {
    cb({ token: getLatestToken() });
  }
});

5.13 Reconnection Handling

const socket = io("http://localhost:3000", {
  reconnection: true,
  reconnectionAttempts: 10,
  reconnectionDelay: 1000,
  reconnectionDelayMax: 5000,
  randomizationFactor: 0.5
});

socket.io.on("reconnect_attempt", (attempt) => {
  console.log(`Reconnection attempt ${attempt}/10`);
  // Update UI: "Reconnecting..."
});

socket.io.on("reconnect", (attempt) => {
  console.log(`Reconnected after ${attempt} attempts`);
  // Re-fetch state, re-subscribe
  socket.emit("sync:state");
});

socket.io.on("reconnect_failed", () => {
  console.log("Failed to reconnect after all attempts");
  // Show "Connection lost" UI with manual retry button
});

// Manual reconnect button
document.getElementById("retry").addEventListener("click", () => {
  socket.connect();
});

Tip

The randomizationFactor (default 0.5) adds jitter to prevent a "thundering herd" when all clients reconnect simultaneously after a server restart. A value of 0.5 means the actual delay will be between 50% and 150% of the computed delay. Do not set this to 0 in production.

5.14 Broadcasting to Specific Users

When users can have multiple tabs or devices connected, use a user-keyed room instead of socket.id:

io.use((socket, next) => {
  socket.data.userId = socket.handshake.auth.userId;
  next();
});

io.on("connection", (socket) => {
  // All of this user's sockets join the same room
  socket.join(`user:${socket.data.userId}`);
});

// Send to a specific user (all their devices/tabs)
function sendToUser(userId, event, data) {
  io.to(`user:${userId}`).emit(event, data);
}

// Check if a user is online
async function isUserOnline(userId) {
  const sockets = await io.in(`user:${userId}`).fetchSockets();
  return sockets.length > 0;
}

5.15 Monitoring Connection Count

// Simple counter
let connectionCount = 0;

io.on("connection", (socket) => {
  connectionCount++;
  console.log(`Connections: ${connectionCount}`);

  socket.on("disconnect", () => {
    connectionCount--;
    console.log(`Connections: ${connectionCount}`);
  });
});

// Using the adapter (more accurate, works across clusters)
setInterval(async () => {
  const sockets = await io.fetchSockets();
  console.log(`Active sockets: ${sockets.length}`);
}, 30000);

// Per-room counts
async function getRoomSize(room) {
  const sockets = await io.in(room).fetchSockets();
  return sockets.length;
}

5.16 Cross-Server Communication (serverSideEmit)

In a multi-server deployment (with Redis or Postgres adapter), serverSideEmit lets servers communicate directly:

// Server A sends to all other servers
io.serverSideEmit("deploy:started", { version: "2.0.0" });

// Server B listens
io.on("deploy:started", ({ version }) => {
  console.log(`Deploy started: ${version}`);
  // Warm caches, prepare for restart, etc.
});

// With acknowledgement — every server responds
try {
  const responses = await io.serverSideEmitWithAck("stats:request");
  // responses is an array, one per server
  const totalConnections = responses.reduce((sum, r) => sum + r.connections, 0);
  console.log(`Total connections across cluster: ${totalConnections}`);
} catch (err) {
  console.log("Not all servers responded");
}

5.17 Using with CORS

CORS is the most common source of connection failures when the client and server are on different origins.

// Allow a single origin
const io = new Server(3000, {
  cors: {
    origin: "https://myapp.com"
  }
});

// Allow multiple origins
const io = new Server(3000, {
  cors: {
    origin: ["https://myapp.com", "https://staging.myapp.com"]
  }
});

// Allow all origins (development only)
const io = new Server(3000, {
  cors: {
    origin: "*"
  }
});

// Full CORS configuration
const io = new Server(3000, {
  cors: {
    origin: "https://myapp.com",
    methods: ["GET", "POST"],
    allowedHeaders: ["Authorization"],
    credentials: true
  }
});

Caution

Never use cors: { origin: "*" } in production. It allows any website to connect to your Socket.IO server. Always specify the exact origins that should be allowed. If you need credentials (cookies, auth headers), you must specify explicit origins — "*" does not work with credentials: true.

5.18 Volatile Events

Volatile events are dropped if the client is not ready to receive them. Useful for data that becomes stale quickly, like cursor positions or live scores:

// Server
setInterval(() => {
  io.volatile.emit("stock:price", {
    symbol: "AAPL",
    price: getCurrentPrice("AAPL"),
    timestamp: Date.now()
  });
}, 100);

// Client — if processing is slow, some ticks are simply skipped
socket.on("stock:price", (data) => {
  updateChart(data);
});

5.19 Event Timeout Patterns

// Client: emit with timeout
socket.timeout(5000).emit("save:data", payload, (err, response) => {
  if (err) {
    showError("Server did not respond in time");
  } else {
    showSuccess("Saved!");
  }
});

// Server: broadcast with ack timeout
io.to("room1").timeout(3000).emit("poll:question", question, (err, responses) => {
  if (err) {
    console.log("Some clients did not respond");
  }
  console.log(`${responses.length} responses collected`);
});

// Async/await version
try {
  const response = await socket.timeout(5000).emitWithAck("save:data", payload);
  console.log("Response:", response);
} catch (err) {
  console.log("Timeout:", err.message);
}

5.20 Using socket.data for Per-Socket State

io.on("connection", (socket) => {
  // Attach arbitrary data to the socket
  socket.data.username = socket.handshake.auth.username;
  socket.data.role = "user";
  socket.data.joinedAt = Date.now();

  // socket.data is included when fetching remote sockets
  socket.on("promote", async (targetId) => {
    const [target] = await io.in(targetId).fetchSockets();
    if (target) {
      target.data.role = "moderator";
    }
  });
});

5.21 Multiple Manager Instances

By default, io() reuses the same Manager for connections to the same host (multiplexing). Force separate connections when needed:

// These share one Manager (one transport connection)
const chatSocket = io("http://localhost:3000/chat");
const feedSocket = io("http://localhost:3000/feed");

// Force a separate connection
const isolatedSocket = io("http://localhost:3000/isolated", {
  forceNew: true
});

// Access the shared manager
chatSocket.io === feedSocket.io; // true
chatSocket.io === isolatedSocket.io; // false

5.22 Handling Middleware Rejection Gracefully

// Server
io.use((socket, next) => {
  if (!socket.handshake.auth.token) {
    const err = new Error("AUTH_REQUIRED");
    err.data = { hint: "Provide auth.token" };
    return next(err);
  }
  next();
});

// Client
socket.on("connect_error", (err) => {
  console.log("Error:", err.message);   // "AUTH_REQUIRED"
  console.log("Details:", err.data);     // { hint: "Provide auth.token" }

  // Update auth and retry
  socket.auth = { token: promptUserForToken() };
  socket.connect();
});

5.23 Catch-All Event Logging (Debug/Development)

// Server — log all incoming events
io.on("connection", (socket) => {
  socket.onAny((event, ...args) => {
    console.log(`[${socket.id}] >>> ${event}`, args);
  });

  socket.onAnyOutgoing((event, ...args) => {
    console.log(`[${socket.id}] <<< ${event}`, args);
  });
});

// Client
socket.onAny((event, ...args) => {
  console.log(`Server event: ${event}`, args);
});

5.24 Graceful Server Shutdown

process.on("SIGTERM", () => {
  console.log("SIGTERM received, shutting down...");

  // Notify all clients
  io.emit("server:shutdown", { reason: "maintenance", reconnectIn: 30 });

  // Close the server (stops accepting new connections)
  io.close(() => {
    console.log("All connections closed");
    process.exit(0);
  });
});

5.25 WebTransport Support

WebTransport is a newer transport that offers lower latency than WebSocket. It must be explicitly enabled:

// Server
const { Server } = require("socket.io");

const io = new Server(3000, {
  transports: ["polling", "websocket", "webtransport"]
});

// Client (browser only, requires HTTPS)
const socket = io("https://myserver.com", {
  transports: ["websocket", "webtransport"]
});

// Check which transport is active
socket.on("connect", () => {
  console.log("Transport:", socket.io.engine.transport.name);
});

WebTransport requires HTTPS and a browser that supports the WebTransport API (Chrome 97+).

5.26 Room Events via Adapter

Track when rooms are created and destroyed:

io.of("/").adapter.on("create-room", (room) => {
  console.log(`Room created: ${room}`);
});

io.of("/").adapter.on("delete-room", (room) => {
  console.log(`Room deleted: ${room}`);
});

io.of("/").adapter.on("join-room", (room, id) => {
  console.log(`Socket ${id} joined room ${room}`);
});

io.of("/").adapter.on("leave-room", (room, id) => {
  console.log(`Socket ${id} left room ${room}`);
});