WebSockets & Real-Time

Real-world analogy

What is it?

WebSockets provide a persistent, bidirectional communication channel between client and server. Unlike HTTP (request-response), WebSocket connections stay open, allowing the server to push data to clients in real-time.

Real-world relevance

Slack, Discord, WhatsApp Web, Google Docs collaborative editing, live sports scores, stock tickers — all use WebSockets for real-time updates.

Key points

• Persistent Connection — Unlike HTTP where each request opens a new connection (connect, send, disconnect, repeat), WebSockets establish a single persistent connection that stays open. Both client and server can send messages at any time without the overhead of reconnecting. This enables true real-time two-way communication with minimal latency.
• Socket.IO — Socket.IO is the most popular WebSocket library for JavaScript. It wraps raw WebSockets with powerful features: automatic reconnection when the connection drops, room-based messaging for group communication, binary data support, and graceful fallbacks for environments where WebSockets are not available.
• Rooms — Rooms let you group WebSocket connections together so you can broadcast messages to specific subsets of users. For example, everyone in Chat Room 5 receives new messages but users in other rooms do not. Rooms are also useful for game lobbies, collaborative document sessions, and per-user notification channels.
• NestJS Gateway — NestJS provides built-in WebSocket support through the @WebSocketGateway() decorator. Define event handlers with @SubscribeMessage('eventName') just like you define HTTP routes with @Get(). The gateway integrates with NestJS dependency injection, guards, and interceptors for clean, organized real-time code.
• Broadcasting — Send messages to a single connected client, a specific room (group of users), or broadcast to every connected user at once. Socket.IO provides flexible methods: socket.emit (one user), socket.to('room').emit (room only), and io.emit (everyone). This gives you precise control over who receives each update.
• Reconnection Logic — Network interruptions are inevitable on mobile devices and unstable connections. Socket.IO handles reconnection automatically with configurable retry intervals and exponential backoff. The client detects disconnection, queues outgoing messages, reconnects seamlessly, and replays missed messages — users barely notice the blip.
• Namespaces for Separation — Socket.IO namespaces let you separate WebSocket logic into distinct channels on the same server. Create /chat for messaging, /notifications for alerts, and /live-scores for sports updates. Each namespace has its own event handlers, rooms, and middleware — keeping your real-time code organized and maintainable.
• Authentication for WebSockets — WebSocket connections need authentication just like HTTP routes. Pass the JWT token during the connection handshake and verify it in a middleware or guard before allowing the socket to join. Without authentication, anyone could connect and listen to private messages. NestJS guards work seamlessly with WebSocket gateways.

Code example

// 1. NestJS WebSocket Gateway 🚀
@WebSocketGateway({
  cors: { origin: '*' },
})
export class ChatGateway {
  @WebSocketServer()
  server: Server;

  // When a client sends a message
  @SubscribeMessage('sendMessage')
  handleMessage(client: Socket, payload: { room: string; text: string }) {
    // Broadcast to everyone in the room
    this.server.to(payload.room).emit('newMessage', {
      text: payload.text,
      sender: client.id,
      timestamp: new Date(),
    });
  }

  // When a client joins a room
  @SubscribeMessage('joinRoom')
  handleJoinRoom(client: Socket, room: string) {
    client.join(room);
    this.server.to(room).emit('userJoined', {
      message: `Someone joined the room!`,
    });
  }
}

// 2. React client — connect and listen 📡
import { io } from 'socket.io-client';

const socket = io('http://localhost:3000');

function ChatRoom({ room }: { room: string }) {
  const [messages, setMessages] = useState<any[]>([]);

  useEffect(() => {
    socket.emit('joinRoom', room);

    socket.on('newMessage', (msg) => {
      setMessages(prev => [...prev, msg]);
    });

    return () => { socket.off('newMessage'); };
  }, [room]);

  const sendMessage = (text: string) => {
    socket.emit('sendMessage', { room, text });
  };

  return (
    <div>
      {messages.map((msg, i) => (
        <div key={i}>{msg.text}</div>
      ))}
      <input placeholder="Type..." onKeyDown={(e) => {
        if (e.key === 'Enter') sendMessage(e.currentTarget.value);
      }} />
    </div>
  );
}

Line-by-line walkthrough

1. 1. 1. NestJS WebSocket Gateway 🚀
2. 2. Decorator that adds metadata or behavior
3. 3.
4. 4.
5. 5. Exporting for use in other files
6. 6. Decorator that adds metadata or behavior
7. 7.
8. 8.
9. 9. When a client sends a message
10. 10. Decorator that adds metadata or behavior
11. 11.
12. 12. Broadcast to everyone in the room
13. 13.
14. 14.
15. 15.
16. 16.
17. 17.
18. 18. Closing block
19. 19.
20. 20. When a client joins a room
21. 21. Decorator that adds metadata or behavior
22. 22.
23. 23.
24. 24.
25. 25.
26. 26.
27. 27. Closing block
28. 28. Closing block
29. 29.
30. 30. 2. React client — connect and listen 📡
31. 31. Importing required dependencies
32. 32.
33. 33. Declaring a variable
34. 34.
35. 35. Declaring a function
36. 36. Declaring a variable
37. 37.
38. 38.
39. 39.
40. 40.
41. 41.
42. 42.
43. 43.
44. 44.
45. 45. Returning a value
46. 46.
47. 47.
48. 48. Declaring a variable
49. 49.
50. 50. Closing block
51. 51.
52. 52. Returning a value
53. 53.
54. 54.
55. 55.
56. 56.
57. 57.
58. 58. Conditional check
59. 59.
60. 60.
61. 61. Closing expression
62. 62. Closing block

Spot the bug

@SubscribeMessage('sendMessage')
handleMessage(client: Socket, payload: { room: string; text: string }) {
  client.emit('newMessage', { text: payload.text });
}

Explain like I'm 5

Fun fact

Hands-on challenge

More resources

• NestJS WebSockets (NestJS Official)
• Socket.io Documentation (Socket.io Official)
• WebSockets in 100 Seconds (Fireship)