Gateway decorator in NestJS - Step-by-Step Execution

Concept Flow - Gateway decorator

Define Gateway Class

↓

Apply @WebSocketGateway() Decorator

↓

NestJS Registers Gateway

↓

Gateway Listens for WebSocket Events

↓

Handle Events with Decorated Methods

↓

Send/Receive Messages via WebSocket

The Gateway decorator marks a class as a WebSocket gateway, enabling NestJS to register it and handle WebSocket events.

Execution Sample

NestJS

import { WebSocketGateway, SubscribeMessage } from '@nestjs/websockets';

@WebSocketGateway()
export class ChatGateway {
  @SubscribeMessage('message')
  handleMessage(client: any, payload: any) {
    return payload;
  }
}

Defines a WebSocket gateway that listens for 'message' events and echoes back the payload.

Execution Table

Step	Action	Evaluation	Result
1	Define ChatGateway class	Class created	Class exists but not registered
2	Apply @WebSocketGateway() decorator	Decorator attaches metadata	Class marked as WebSocket gateway
3	NestJS scans and registers gateway	Gateway registered in WebSocket server	Gateway ready to accept connections
4	Client connects via WebSocket	Connection established	Client connected to gateway
5	Client sends 'message' event with payload	handleMessage method triggered	Payload received and returned
6	Gateway sends response back to client	Response sent	Client receives echoed payload

💡 Execution stops when client disconnects or server shuts down

Variable Tracker

Variable	Start	After Step 2	After Step 3	After Step 5	Final
ChatGateway	Class defined	Marked as gateway	Registered gateway instance	handleMessage method called	Gateway active and handling events
client	undefined	undefined	undefined	Connected client object	Client connected or disconnected
payload	undefined	undefined	undefined	Message data from client	Payload processed and returned

Key Moments - 3 Insights

Why does the class need the @WebSocketGateway() decorator?

The decorator tells NestJS this class is a WebSocket gateway so it can register and manage it, as shown in execution_table step 2 and 3.

How does NestJS know which method handles a specific WebSocket event?

Methods decorated with @SubscribeMessage('eventName') handle that event, like handleMessage for 'message' in step 5.

What happens if the client sends an event not handled by any method?

No method is triggered, so no response is sent; the gateway ignores unknown events, as no matching @SubscribeMessage exists.

Visual Quiz - 3 Questions

Look at the execution table, at which step does NestJS register the gateway?

A Step 5

B Step 2

C Step 3

D Step 1

💡 Hint

Check the 'Action' and 'Result' columns in step 3 for gateway registration

According to variable_tracker, what is the state of 'payload' after step 5?

A undefined

B Message data from client

C Class defined

D Client connected

💡 Hint

Look at the 'payload' row under 'After Step 5' column

If the @SubscribeMessage decorator is removed from handleMessage, what changes in the execution?

A handleMessage will not be triggered on 'message' events

B Gateway will not register

C Client cannot connect

D Payload will be automatically returned

💡 Hint

Refer to key_moments about how NestJS knows which method handles events

Concept Snapshot

Use @WebSocketGateway() on a class to mark it as a WebSocket gateway.
Use @SubscribeMessage('event') on methods to handle specific events.
NestJS registers the gateway and listens for WebSocket connections.
Methods receive client and payload, and can return responses.
Gateway runs as part of NestJS WebSocket server.

Full Transcript

The Gateway decorator in NestJS marks a class as a WebSocket gateway. When you add @WebSocketGateway() above a class, NestJS knows to register it as a WebSocket server handler. Inside this class, methods decorated with @SubscribeMessage('eventName') listen for specific WebSocket events from clients. When a client connects and sends an event, the corresponding method runs, receiving the client and the message payload. The method can return data that is sent back to the client. This flow allows real-time communication between server and clients using WebSockets. The execution table shows each step from class definition, decoration, registration, client connection, event handling, to response sending. Variables like the gateway instance, client, and payload change state as events happen. Key moments clarify why decorators are needed and how event handling works. The visual quiz tests understanding of registration steps, variable states, and decorator roles. This helps beginners see how NestJS WebSocket gateways work step-by-step.