WebSocket gateway creation in NestJS - Step-by-Step Execution

Concept Flow - WebSocket gateway creation

Start NestJS App

↓

Define Gateway Class

↓

Add @WebSocketGateway Decorator

↓

Implement Event Handlers

↓

NestJS Creates WebSocket Server

↓

Client Connects

↓

Handle Messages & Send Responses

↓

Client Disconnects

↓

End

The flow shows how NestJS creates a WebSocket gateway class, sets up event handlers, starts the server, and manages client connections and messages.

Execution Sample

NestJS

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

@WebSocketGateway()
export class ChatGateway {
  @SubscribeMessage('message')
  handleMessage(@MessageBody() data: string): string {
    return `Received: ${data}`;
  }
}

This code creates a WebSocket gateway that listens for 'message' events and replies with a confirmation string.

Execution Table

Step	Action	Input/Event	Internal State	Output/Response
1	NestJS starts and scans for gateways	App start	Gateway class registered	WebSocket server ready
2	Client connects	Client connects to WS server	Connection established	Connection acknowledged
3	Client sends 'message' event	'message' with data='Hello'	handleMessage called with data='Hello'	Returns 'Received: Hello'
4	Server sends response	Send response to client	Response sent	Client receives 'Received: Hello'
5	Client disconnects	Client closes connection	Connection closed	Cleanup done
6	End	No more events	Idle	No output

💡 Execution stops when client disconnects and no more events occur.

Variable Tracker

Variable	Start	After Step 2	After Step 3	After Step 4	Final
data	undefined	undefined	'Hello'	'Hello'	undefined
connection	none	established	established	established	closed
response	none	none	none	'Received: Hello'	none

Key Moments - 3 Insights

Why does the handleMessage method receive the message data as a parameter?

Because the @SubscribeMessage decorator listens for the 'message' event and passes the message payload to the method as the parameter decorated with @MessageBody, as shown in step 3 of the execution_table.

What happens if the client sends a different event name?

The gateway will ignore it unless there is a method decorated with @SubscribeMessage for that event. Only events with matching handlers trigger methods, as seen in step 3 where 'message' triggers handleMessage.

How does the server send a response back to the client?

The method returns a value which NestJS sends automatically as a response to the client event, demonstrated in step 4 where the returned string is sent back.

Visual Quiz - 3 Questions

Look at the execution_table, what is the value of 'data' at Step 3?

A undefined

B 'Hello'

C 'Received: Hello'

D null

💡 Hint

Check the 'Input/Event' and 'Internal State' columns at Step 3 in the execution_table.

At which step does the client disconnect from the WebSocket server?

A Step 2

B Step 3

C Step 5

D Step 6

💡 Hint

Look for the 'Client disconnects' action in the execution_table.

If the client sends an event named 'ping' instead of 'message', what happens?

A No method is called, no response sent

B handleMessage is called with 'ping' data

C Server crashes

D Client disconnects immediately

💡 Hint

Refer to the key_moments explanation about event names and handlers.

Concept Snapshot

NestJS WebSocket Gateway:
- Use @WebSocketGateway() on a class
- Use @SubscribeMessage('event') on methods
- Methods receive data via @MessageBody()
- Return value is sent back to client
- Handles client connect, message, disconnect
- Easy real-time communication setup

Full Transcript

This visual execution trace shows how to create a WebSocket gateway in NestJS. First, NestJS starts and registers the gateway class decorated with @WebSocketGateway. When a client connects, the server establishes a connection. When the client sends a 'message' event with data, the handleMessage method is called with that data. The method returns a string response which NestJS sends back to the client. Finally, when the client disconnects, the connection closes and the server cleans up. Variables like 'data', 'connection', and 'response' change state during these steps. Common confusions include how the message data is passed to the method, what happens with unknown events, and how responses are sent. The quizzes test understanding of these execution steps. This process enables easy real-time communication using WebSockets in NestJS.