Socket.IO Namespaces: Channels on One Connection

Why it exists

Real-time applications often need to partition communication logic. For example, you might have general user events and separate, privileged admin events. Opening a new WebSocket connection for each logical division is inefficient and resource-intensive. Namespaces were created to provide this separation over a single, shared connection.

The mental model

Think of a single WebSocket connection as an apartment building's main entrance. A namespace is like a specific apartment inside (/admin, /orders). Each apartment has its own set of rules (middleware), private rooms, and dedicated event handlers, but everyone uses the same front door to get in. This is called multiplexing: routing different types of traffic over one channel.

How it works

On the server, you define a namespace with io.of('/your-namespace'). This creates a channel that is completely separate from the default / namespace. It has its own event handlers, rooms, and can have its own middleware for tasks like authentication. On the client, you connect to it with io('/your-namespace'). Socket.IO handles routing the packets sent over the single underlying connection to the correct namespace logic on the server.

When to use it

Use namespaces for broad, architectural separation in your application. The two primary use cases are: first, creating a privileged area for specific users, like an /admin namespace with its own authentication logic. Second, for multi-tenant applications, where you can dynamically create a separate namespace for each customer or workspace, ensuring their data and events are isolated.

When not to use it

Do not use namespaces for simple, transient groupings of sockets. That is what rooms are for. If you just need to broadcast a message to a subset of connected clients within the same logical context (like users in a specific chat session), use socket.join('room-name'). Using a namespace for this is overkill and adds unnecessary complexity.

One canonical example

To create a separate, protected area for administrators:

Server-side:

const adminNamespace = io.of('/admin');
adminNamespace.use((socket, next) => {

// Your authentication logic here

next();
});
adminNamespace.on('connection', socket => {
socket.on('delete user', () => { /* ... */ });
});

Client-side:

const adminSocket = io('/admin');
adminSocket.emit('delete user', userId);

This ensures only authenticated clients can connect to the /admin channel and access its specific events.