WebSockets

HTTP is half-duplex: the client asks, the server answers, and the connection closes. WebSockets flip that model — after a single HTTP upgrade handshake the connection stays open, and either side can push data at any moment. Socket.IO wraps raw WebSockets with rooms, namespaces, acknowledgements, automatic reconnection, and transparent fallbacks, making real-time features practical without re-inventing the protocol layer.

HTTP vs WebSocket

The upgrade from HTTP to WebSocket happens via a standard header exchange: the client sends Upgrade: websocket, the server responds with 101 Switching Protocols, and from that point the TCP socket is handed to the WebSocket layer.

Why Socket.IO over Raw WebSockets?

Server Setup

Socket.IO attaches to a plain Node http.Server, not to the Express app directly. Create the HTTP server first, pass it to Socket.IO, then listen on that server — not on app.listen().

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

const app        = express();
const httpServer = http.createServer(app);
const io         = new Server(httpServer, {
  cors: {
    origin:      'http://localhost:5173',  // your frontend origin
    credentials: true,
  },
});

// Express routes work exactly as before
app.get('/api/status', (_req, res) => res.json({ ok: true }));

// All Socket.IO logic under io.on()
io.on('connection', (socket) => {
  console.log('connected:', socket.id);
});

httpServer.listen(3000, () => console.log('Listening on :3000'));

Connection Lifecycle

io.on('connection', (socket) => {
  console.log(`+ connected  ${socket.id}`);

  socket.on('ping', (callback) => {
    if (typeof callback === 'function') callback({ pong: Date.now() });
  });

  socket.on('disconnect', (reason) => {
    console.log(`- disconnected ${socket.id} (${reason})`);
  });
});

Each socket object inside io.on('connection') represents one client. socket.id is stable for the lifetime of the connection. Custom data tied to a socket (username, room, role) is stored on socket.data — a plain object that is not sent to the client.

Emitting Events — Who Receives What

The most important thing to get right with Socket.IO: every emit target is a different audience. Learn these five methods before writing any real-time feature.

Rooms

Rooms are named groups of sockets. Every socket is automatically in a private room named after its own socket.id, so you can DM a specific socket with io.to(socket.id).emit(). You can also create named rooms for chat channels, game lobbies, or any grouping concept.

io.on('connection', (socket) => {

  socket.on('join-room', ({ room, username }) => {
    socket.join(room);                  // socket is now in this room
    socket.data.username = username;
    socket.data.room     = room;

    // Notify everyone else in the room (not the joiner)
    socket.to(room).emit('user-joined', { username });
  });

  socket.on('send-message', ({ message }) => {
    const { room, username } = socket.data;
    if (!room) return;

    // io.to() includes the sender — they see their own message
    io.to(room).emit('new-message', { username, message, ts: Date.now() });
  });

  socket.on('leave-room', () => {
    const { room, username } = socket.data;
    socket.leave(room);
    socket.to(room).emit('user-left', { username });
    socket.data.room = null;
  });

  socket.on('disconnect', () => {
    // socket automatically leaves all rooms on disconnect
    const { room, username } = socket.data;
    if (room) socket.to(room).emit('user-left', { username });
  });
});

A socket can be in multiple rooms simultaneously. socket.rooms is a Set containing the current room names (always includes socket.id). socket.leave(room) removes it from that room without disconnecting.

Socket.IO Middleware — Authentication

io.use() works like Express middleware but runs once per connection attempt, before io.on('connection') fires. Calling next(new Error(...)) rejects the connection; the client receives a connect_error event with the error message.

const jwt    = require('jsonwebtoken');
const SECRET = process.env.JWT_SECRET;

io.use((socket, next) => {
  // Client passes token at connection time:
  // const socket = io(URL, { auth: { token: 'Bearer eyJ...' } });
  const token = socket.handshake.auth.token;

  if (!token) {
    return next(new Error('Authentication required'));
  }

  try {
    socket.data.user = jwt.verify(token, SECRET, { algorithms: ['HS256'] });
    next();
  } catch (err) {
    const message = err.name === 'TokenExpiredError' ? 'Token expired' : 'Invalid token';
    next(new Error(message));
  }
});

io.on('connection', (socket) => {
  // socket.data.user is populated — safe to read
  console.log('authed user:', socket.data.user.sub);
});

Acknowledgements

Acknowledgements turn a fire-and-forget emit into a round-trip. The client passes a callback as the last argument to socket.emit(); the server calls it with a response. This replaces the need for a separate "response" event and removes the request-ID tracking problem entirely.

// ── Server ────────────────────────────────────────────────────────────
socket.on('create-item', async (data, callback) => {
  if (typeof callback !== 'function') return;  // guard: client may not pass one

  if (!data?.name?.trim()) {
    return callback({ error: 'name is required' });
  }

  const item = await db.insert(data);
  callback({ success: true, item });   // triggers the client callback
});


// ── Client ────────────────────────────────────────────────────────────
socket.emit('create-item', { name: 'Widget' }, (response) => {
  if (response.error) {
    console.error('Failed:', response.error);
  } else {
    console.log('Created:', response.item);
  }
});


// ── In tests (socket.io-client) ───────────────────────────────────────
const response = await new Promise((resolve) => {
  client.emit('create-item', { name: 'Widget' }, resolve);
});
expect(response.success).toBe(true);

Namespaces

Namespaces multiplex multiple logical connections over a single TCP socket. The default namespace is /. A named namespace io.of('/chat') is a fully independent channel with its own connection events, middleware, and rooms — useful for separating concerns (chat vs admin vs notifications) without spinning up multiple servers.

// Server
const chat  = io.of('/chat');
const admin = io.of('/admin');

chat.use(requireAuth);   // middleware only on /chat
admin.use(requireAdmin);

chat.on('connection', (socket) => { /* chat events */ });
admin.on('connection', (socket) => { /* admin events */ });

// Client
const chatSocket  = io('http://localhost:3000/chat',  { auth: { token } });
const adminSocket = io('http://localhost:3000/admin', { auth: { token } });

Testing with socket.io-client

Socket.IO tests use the socket.io-client package to create real in-process connections to a test server. Listen on port 0 (OS assigns a free port), read it back from httpServer.address().port, and connect the test client there.

// jest.config.js
module.exports = {
  testEnvironment: 'node',
  forceExit:       true,   // socket.io keeps the event loop open
  clearMocks:      true,
};


// chat.test.js
const { io: ioc }        = require('socket.io-client');
const { httpServer, io } = require('./server');

let port;

// Helper: resolve when an event fires once
function waitForEvent(socket, event) {
  return new Promise((resolve) => socket.once(event, resolve));
}

// Helper: resolve when the client is connected
function connect(opts = {}) {
  return new Promise((resolve) => {
    const client = ioc(`http://localhost:${port}`, {
      transports: ['websocket'],  // skip polling, faster tests
      forceNew:   true,           // each call = fresh socket (no reuse)
      ...opts,
    });
    client.once('connect', () => resolve(client));
  });
}

// Helper: small pause so a server event can propagate to recipients
const tick = () => new Promise((r) => setTimeout(r, 20));

beforeAll((done) => {
  httpServer.listen(() => {
    port = httpServer.address().port;
    done();
  });
});

afterAll((done) => {
  io.close();               // closes all sockets + the http server internally
  httpServer.close(done);
});

test('server echoes message to sender', async () => {
  const client = await connect();
  client.emit('join-room', { room: 'test', username: 'alice' });
  await tick();

  client.emit('send-message', { message: 'hello' });
  const msg = await waitForEvent(client, 'new-message');
  expect(msg.message).toBe('hello');
  client.disconnect();
});