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.

Practice

1.

What is the main purpose of the @WebSocketGateway() decorator in NestJS?

easy

A. To turn a class into a WebSocket gateway for real-time communication

B. To create a REST API controller

C. To define a database entity

D. To handle HTTP middleware

Solution

1. Step 1: Understand the role of @WebSocketGateway()

   This decorator marks a class as a WebSocket gateway, enabling real-time communication between server and clients.

2. Step 2: Compare with other options

   Options B, C, and D relate to REST controllers, database entities, and middleware, which are unrelated to WebSocket gateways.

3. Final Answer:

   To turn a class into a WebSocket gateway for real-time communication -> Option A

4. Quick Check:

   @WebSocketGateway() creates WebSocket gateways [OK]

Hint: Remember: Gateway decorator = real-time WebSocket server [OK]

Common Mistakes:

• Confusing WebSocketGateway with REST controllers
• Thinking it creates database entities
• Assuming it handles HTTP middleware

2.

Which of the following is the correct syntax to create a WebSocket gateway with a custom namespace /chat?

?

easy

A. @WebSocketGateway(namespace: '/chat')
export class ChatGateway {}

B. @WebSocketGateway('/chat')
export class ChatGateway {}

C. @WebSocketGateway({ namespace: '/chat' })
export class ChatGateway {}

D. @WebSocketGateway({ path: '/chat' })
export class ChatGateway {}

Solution

1. Step 1: Recall the correct options object syntax

   The @WebSocketGateway() decorator accepts an options object where namespace is a valid key to set the namespace.

2. Step 2: Evaluate each option

   @WebSocketGateway({ namespace: '/chat' }) export class ChatGateway {} correctly uses { namespace: '/chat' }. @WebSocketGateway('/chat') export class ChatGateway {} incorrectly passes a string directly. @WebSocketGateway(namespace: '/chat') export class ChatGateway {} uses invalid syntax. @WebSocketGateway({ path: '/chat' }) export class ChatGateway {} uses path which is not the correct key for namespace.

3. Final Answer:

   @WebSocketGateway({ namespace: '/chat' }) export class ChatGateway {} -> Option C

4. Quick Check:

   Use options object with namespace key [OK]

Hint: Use options object with namespace key for custom namespace [OK]

Common Mistakes:

• Passing namespace as a direct string argument
• Using invalid syntax inside decorator
• Confusing 'path' with 'namespace'

3.

Given the following code, what will be the output when a client connects?

@WebSocketGateway()
export class MyGateway {
  handleConnection(client: any) {
    console.log('Client connected');
  }
}

medium

A. Nothing happens because handleConnection is not called automatically

B. The server crashes due to missing WebSocket server initialization

C. An error occurs because handleConnection is missing a decorator

D. The message 'Client connected' is logged to the console when a client connects

Solution

1. Step 1: Understand handleConnection behavior

   In NestJS WebSocket gateways, handleConnection is a lifecycle method called automatically when a client connects.

2. Step 2: Analyze the code output

   The method logs 'Client connected' to the console, so this message appears on each client connection.

3. Final Answer:

   The message 'Client connected' is logged to the console when a client connects -> Option D

4. Quick Check:

   handleConnection logs message on client connect [OK]

Hint: handleConnection runs automatically on client connect [OK]

Common Mistakes:

• Thinking handleConnection needs a decorator
• Assuming no output without explicit event listener
• Believing server crashes without manual init

4.

Identify the error in this WebSocket gateway code:

@WebSocketGateway()
export class AppGateway {
  @SubscribeMessage('message')
  handleMessage(client, payload) {
    client.emit('message', payload);
  }
}

medium

A. The client object does not have an emit method; it should use client.send

B. The method handleMessage should return the payload instead of emitting

C. The @SubscribeMessage decorator is missing parentheses

D. The method handleMessage must be async

Solution

1. Step 1: Understand @SubscribeMessage handler behavior

   In NestJS, message handlers should return the response payload, not emit directly on the client.

2. Step 2: Analyze the code's client.emit usage

   Calling client.emit is incorrect; the framework handles sending the return value automatically.

3. Final Answer:

   The method handleMessage should return the payload instead of emitting -> Option B

4. Quick Check:

   Return payload in handler, don't emit manually [OK]

Hint: Return data in handler; don't call client.emit manually [OK]

Common Mistakes:

• Calling client.emit instead of returning data
• Thinking @SubscribeMessage needs parentheses
• Assuming handler must be async always

5.

You want to create a WebSocket gateway that listens on port 8081 and uses the namespace /notifications. Which of the following is the correct way to define this gateway?

hard

A. @WebSocketGateway({ port: 8081, namespace: '/notifications' })
export class NotificationGateway {}

B. @WebSocketGateway('/notifications', 8081)
export class NotificationGateway {}

C. @WebSocketGateway({ port: 8081 })
@WebSocketGateway({ namespace: '/notifications' })
export class NotificationGateway {}

D. @WebSocketGateway(8081, { namespace: '/notifications' })
export class NotificationGateway {}

Solution

1. Step 1: Recall the correct options object usage

   The @WebSocketGateway() decorator accepts a single options object where you can specify both port and namespace.

2. Step 2: Evaluate each option

   @WebSocketGateway({ port: 8081, namespace: '/notifications' }) export class NotificationGateway {} correctly passes an object with both port and namespace. @WebSocketGateway(8081, { namespace: '/notifications' }) export class NotificationGateway {} incorrectly uses positional arguments mixing number and object. @WebSocketGateway({ port: 8081 }) @WebSocketGateway({ namespace: '/notifications' }) export class NotificationGateway {} uses two decorators which is invalid. @WebSocketGateway('/notifications', 8081) export class NotificationGateway {} uses positional arguments in wrong order and types.

3. Final Answer:

   @WebSocketGateway({ port: 8081, namespace: '/notifications' }) export class NotificationGateway {} -> Option A

4. Quick Check:

   Use single options object for port and namespace [OK]

Hint: Use one options object with port and namespace keys [OK]

Common Mistakes:

• Passing port and namespace as separate arguments
• Using multiple @WebSocketGateway decorators
• Mixing argument types and order incorrectly