How do you build real-time features with WebSocket gateways?

Question

Accepted Answer

NestJS supports **real-time, bidirectional communication** via **WebSocket gateways** — classes decorated with `@WebSocketGateway()` that handle WebSocket connections and messages (typically over Socket.IO). They enable features like chat, live notifications, and live dashboards, using the same NestJS structure (DI, decorators).

## Defining a gateway

```ts
import { WebSocketGateway, SubscribeMessage, MessageBody, WebSocketServer } from "@nestjs/websockets";
import { Server } from "socket.io";

@WebSocketGateway({ cors: true })
export class ChatGateway {
  @WebSocketServer()
  server: Server;                        // the Socket.IO server instance

// handle a 'message' event from a client
  @SubscribeMessage("message")
  handleMessage(@MessageBody() data: { text: string }) {
    // BROADCAST to all connected clients
    this.server.emit("message", data);   // everyone receives the message
  }
}
```

A gateway uses `@SubscribeMessage("event")` to handle incoming events (analogous to `@Post` for HTTP) and the injected `server` to **emit** events back to clients — `server.emit` broadcasts to everyone.

## Connection lifecycle hooks

```ts
export class ChatGateway implements OnGatewayConnection, OnGatewayDisconnect {
  handleConnection(client: Socket) {
    console.log(`Client connected: ${client.id}`);   // a user joined
  }
  handleDisconnect(client: Socket) {
    console.log(`Client disconnected: ${client.id}`); // a user left — clean up
  }
}
```

Gateways can react to clients connecting and disconnecting — useful for presence tracking and cleanup.

## Targeting specific clients and rooms

```ts
@SubscribeMessage("joinRoom")
handleJoin(@ConnectedSocket() client: Socket, @MessageBody() room: string) {
  client.join(room);                              // add the client to a room
}

@SubscribeMessage("roomMessage")
sendToRoom(@MessageBody() data: { room: string; text: string }) {
  this.server.to(data.room).emit("message", data.text);   // emit only to that room
  // client.emit(...) → just that client; server.emit(...) → everyone
}
```

**Rooms** group clients (e.g. a chat room, a document's collaborators), letting you broadcast to specific subsets rather than everyone — essential for scoped real-time features.

## Gateways reuse NestJS features

```text
Gateways are providers → they support dependency injection (inject services),
and can use guards, pipes, interceptors, and filters — just like HTTP controllers.
→ The same structure/patterns apply to real-time as to REST.
```

## Scaling WebSockets

```text
⚠️ WebSocket connections are STATEFUL and live on ONE server instance.
To scale across multiple instances, use a Redis adapter (socket.io-redis) so
broadcasts/rooms work across all instances. (Like sessions, don't keep state in
one process's memory when scaling horizontally.)
```

## Why it matters

WebSocket gateways are how NestJS supports **real-time, bidirectional features** — chat, live notifications, presence, collaborative editing, live dashboards, multiplayer interactions — that REST's request-response model can't provide (the server can push to clients, not just respond to requests).

Understanding them is valuable senior-level knowledge for building modern interactive applications.

The key strength is that gateways fit NestJS's familiar structure: they're providers supporting **dependency injection** and can use **guards, pipes, interceptors, and filters** just like HTTP controllers, so the same patterns and code organization apply to real-time as to REST.

Knowing how to handle events (`@SubscribeMessage`), broadcast to clients (`server.emit`), use **rooms** to scope broadcasts to relevant subsets (chat rooms, document collaborators), and manage the connection lifecycle (presence, cleanup) covers the practical real-time toolkit.

Critically important is the **scaling consideration**: WebSocket connections are stateful and tied to a single server instance, so scaling horizontally requires a **Redis adapter** to coordinate broadcasts/rooms across instances (a common pitfall — like sessions, real-time state can't live in one process's memory when running multiple instances).

This is an important, increasingly-relevant capability for building the real-time, interactive experiences that modern users expect, and NestJS's clean integration makes it accessible while reusing the framework's structure.