Rooms - live.room()

Rooms bundle data, presence, cursors, and scoped actions into a single declaration. They are the high-level primitive for collaborative features where multiple related streams share the same topic scope.

Declaring a room

// src/live/collab.js
import { live } from 'svelte-realtime/server';

export const board = live.room({
  topic: (ctx, boardId) => 'board:' + boardId,
  init: async (ctx, boardId) => db.cards.forBoard(boardId),
  presence: (ctx) => ({ name: ctx.user.name, avatar: ctx.user.avatar }),
  cursors: true,
  guard: async (ctx) => {
    if (!ctx.user) throw new LiveError('UNAUTHORIZED');
  },
  actions: {
    addCard: async (ctx, boardId, title) => {
      const card = await db.cards.insert({ boardId, title });
      ctx.publish('created', card);
      return card;
    }
  }
});

Using a room on the client

On the client, the room export becomes an object with sub-streams and actions. Room actions receive the same leading arguments as the topic function (boardId in this case), followed by any action-specific arguments:

<script>
  import { board } from '$live/collab';

  const data = board.data(boardId);         // main data stream
  const users = board.presence(boardId);     // presence stream
  const cursors = board.cursors(boardId);    // cursor stream
</script>

{#each $data as card (card.id)}
  <Card {card} />
{/each}

<button onclick={() => board.addCard(boardId, 'New card')}>Add</button>

Each sub-stream (data, presence, cursors) is a standard Svelte store. They follow the same lifecycle as regular streams → undefined while loading, data when ready, { error } on failure.

Room hooks shortcut

Rooms expose a .hooks property for one-liner wiring in hooks.ws.js:

// src/hooks.ws.js
import { board } from './live/collab.js';

export const { message, close, unsubscribe } = board.hooks;

This exports the message, close, and unsubscribe hooks pre-wired for the room’s streams and lifecycle.

Rooms combine Streams, Merge Strategies (presence, cursor, crud), and Auth into a single cohesive unit. See those pages for details on each underlying primitive.