Rooms

A room is a named group of browser tabs, such as everyone looking at one chat thread or editing one record. Send a message to a room and only its members get it, on every API instance. A room is any string your feature picks, for example chat:42. This guide adds rooms to the fictional @acme/chat plugin from WebSocket.

Before you beginCopy Anchor Link

• The /api/ws endpoint, from Set up the endpoint.
• The chatChannel from Define a channel, which carries the chat messages to the browser.
• A top-level API module for the server socket. Here it is rooms, built with buildModule from your plugin's @/api/builders.

import { buildWebSocket } from "@vitnode/core/api/lib/websocket"
import { wsRegistry } from "@vitnode/core/ws/registry"

export interface RoomMessage {
  clientId: string
  roomId: string
  type: "join" | "leave"
}

export const roomsSocket = buildWebSocket<RoomMessage>({
  id: "presence",
  onMessage: ({ data, ws }) => {
    const room = `chat:${data.roomId}`

    if (data.type === "join") {
      wsRegistry.join(ws, room, data.clientId)
    } else {
      wsRegistry.leave(ws, room, data.clientId)
    }
  },
})

import { buildModule } from "@/api/builders"

import { roomsSocket } from "./rooms.socket"

export const roomsModule = buildModule({
  name: "rooms",
  webSockets: [roomsSocket],
})

import { createWebSocketChannel } from "@vitnode/core/ws/types"

import type { RoomMessage } from "../api/modules/rooms/rooms.socket"

export const roomsChannel = createWebSocketChannel<RoomMessage>({
  pluginId: "@acme/chat",
  module: "rooms",
  id: "presence",
})

import { useVitNodeWebSocket } from "@vitnode/core/ws/use-websocket"
import { useEffect, useState } from "react"

import { chatChannel, roomsChannel } from "../ws/chat.channel"

export const ChatRoom = ({ roomId }: { roomId: string }) => {
  const [clientId] = useState(() => crypto.randomUUID())
  const [messages, setMessages] = useState<string[]>([])
  const { connectionId, send } = useVitNodeWebSocket(roomsChannel)

  useVitNodeWebSocket(chatChannel, {
    onMessage: payload => {
      if (payload.roomId === roomId) {
        setMessages(prev => [...prev, payload.message])
      }
    },
  })

  useEffect(() => {
    if (!connectionId) return
    send({ clientId, roomId, type: "join" })

    return () => {
      send({ clientId, roomId, type: "leave" })
    }
  }, [clientId, connectionId, roomId, send])

  return (
    <ul>
      {messages.map((message, i) => (
        <li key={i}>{message}</li>
      ))}
    </ul>
  )
}

c.get("realtime").toRoom(`chat:${roomId}`, chatChannel, {
  roomId,
  message: "Hello!",
  senderId: user.id,
})

Check the resultCopy Anchor Link

Open the chat room page for room 42 in two browsers, and room 7 in a third. Send a message to room 42. The first two show it right away, and the third shows nothing. Close one tab of a browser that has two tabs on room 42, send again, and its other tab still gets the message.

Clean up when a socket closesCopy Anchor Link

A socket that closes leaves all of its rooms. Use wsRegistry.onConnectionClose to update your own state, such as an "online now" list. Register the listener once, at module load:

import { wsRegistry } from "@vitnode/core/ws/registry"

const online = new Map<string, Set<string>>()

wsRegistry.onConnectionClose((ws, left) => {
  for (const { memberId, room } of left) {
    online.get(room)?.delete(memberId)
  }
})

left holds every { memberId, room } the socket was in.

Inspect roomsCopy Anchor Link

All wsRegistry methods act on the current instance only.

Rooms on several instancesCopy Anchor Link

With REDIS_URL set, toRoom also publishes the message over Redis, and every other instance delivers it to its own members. Room membership itself stays local to each instance.

When an instance keeps per-room state in memory, it can follow the other instances with helpers from @vitnode/core/ws/registry:

import {
  onInstanceMessage,
  onRemoteRoomMessage,
  publishToInstances,
} from "@vitnode/core/ws/registry"

• onRemoteRoomMessage((room, id, data) => ...) sees room messages from other instances before they reach local sockets. A collaborative document uses it to apply the same edit to its own copy.
• publishToInstances(topic, data) and onInstanceMessage(({ topic, data, origin }) => ...) exchange data between instances that never reaches a socket, such as each instance's list of members. Republish it periodically and let entries from a silent instance expire, so a crashed instance leaves no ghosts.

Both listeners return a function that removes them. Without Redis, all of this works on a single instance with no extra setup. toRoom delivers locally, and instance messages go nowhere.

RelatedCopy Anchor Link

• Reconnects and missed messages
• Live refresh: Content Engine's authorized rooms for AdminCP lists and comment threads, built on these primitives.