This document details the Socket.IO integration in NestJS, which provides a feature-rich WebSocket implementation with support for rooms, namespaces, broadcasting, and horizontal scaling. The integration is implemented through the @nestjs/platform-socket.io package, which serves as a platform adapter on top of the abstract @nestjs/websockets layer.
The core of the integration is managed by the SocketModule, which coordinates the discovery of gateways and their attachment to the underlying Socket.IO server instances.
The Socket.IO integration follows NestJS's platform adapter pattern, where an abstract WebSocket layer is implemented by a concrete Socket.IO adapter.
The following diagram illustrates how the core WebSocket components relate to the Socket.IO platform entities.
Sources: packages/websockets/socket-module.ts27-34 packages/websockets/web-sockets-controller.ts29-43 packages/platform-socket.io/adapters/io-adapter.ts14-20
The IoAdapter is the concrete implementation of the AbstractWsAdapter. It wraps the socket.io library to provide NestJS-compatible hooks for server creation and message handling.
The IoAdapter.create() method handles the instantiation of the Socket.IO server. If an HTTP server is already provided in the constructor, it attaches the Socket.IO instance to that existing server when the port is set to 0.
| Method | Role | Implementation Detail |
|---|---|---|
create() | Entry point | Handles namespace logic via server.of(namespace) packages/platform-socket.io/adapters/io-adapter.ts17-30 |
createIOServer() | Low-level init | Instantiates new Server(port, options) packages/platform-socket.io/adapters/io-adapter.ts32-37 |
bindMessageHandlers() | Event binding | Iterates over MessageMappingProperties and sets up fromEvent(socket, message) packages/platform-socket.io/adapters/io-adapter.ts39-69 |
Socket.IO supports acknowledgments (acks). The IoAdapter includes a mapPayload() function that detects if the last argument of an incoming message is a function (the callback for the ack).
Sources: packages/platform-socket.io/adapters/io-adapter.ts72-89 packages/websockets/adapters/ws-adapter.ts13-17
The WebSocketsController is the internal engine that connects decorated Gateway instances to the network server.
Sources: packages/websockets/socket-module.ts68-95 packages/websockets/web-sockets-controller.ts45-64 packages/websockets/web-sockets-controller.ts98-101
The controller manages three primary lifecycle events for every gateway:
subscribeInitEvent calls afterInit if implemented. packages/websockets/web-sockets-controller.ts148-152subscribeConnectionEvent calls handleConnection using an RxJS distinctUntilChanged pipe to ensure stable connection handling. packages/websockets/web-sockets-controller.ts154-162subscribeDisconnectEvent calls handleDisconnect. packages/websockets/web-sockets-controller.ts164-170Gateways are configured using the GatewayMetadata interface, which mirrors many of the native socket.io options.
GatewayMetadata)| Property | Type | Description |
|---|---|---|
namespace | string | RegExp | Socket.IO namespace for the gateway packages/websockets/interfaces/gateway-metadata.interface.ts12 |
path | string | The path to capture (default /socket.io) packages/websockets/interfaces/gateway-metadata.interface.ts17 |
cors | CorsOptions | Configuration for Cross-Origin Resource Sharing packages/websockets/interfaces/gateway-metadata.interface.ts107 |
transports | Array<'polling' | 'websocket'> | Enabled low-level transports packages/websockets/interfaces/gateway-metadata.interface.ts72 |
Sources: packages/websockets/interfaces/gateway-metadata.interface.ts8-123
While the core IoAdapter handles single-node communication, NestJS supports horizontal scaling via Socket.IO Redis adapters.
Sources: packages/platform-socket.io/adapters/io-adapter.ts14-30 integration/websockets/e2e/gateway.spec.ts54-69
The SocketModule ensures that all active servers are gracefully closed when the application context is destroyed.
close() method in SocketModule retrieves all servers from the SocketsContainer. packages/websockets/socket-module.ts105-106close() method for each. packages/websockets/socket-module.ts107-110dispose() on the adapter to clear registries. packages/websockets/socket-module.ts111Sources: packages/websockets/socket-module.ts97-114 packages/platform-socket.io/adapters/io-adapter.ts91-97
Refresh this wiki