Quickstart

Audience: users.

This walkthrough shows the intended first integration flow for Roomful.

1) Install Core

npm install @roomful/core@beta

2) Create and Connect a Room

import { createRoom } from '@roomful/core';

const room = createRoom('my-first-room', {
  transport: 'auto',
  presence: {
    name: 'Alice',
    color: '#4F46E5',
  },
});

await room.connect();

Transport support in the current baseline:

• Available: auto, broadcast, webrtc, websocket
• auto order: broadcast -> webrtc -> websocket -> in-memory

WebRTC cross-machine baseline:

const room = createRoom('my-first-room', {
  transport: 'webrtc',
  relayUrl: 'ws://localhost:8787',
  presence: { name: 'Alice', color: '#4F46E5' },
});

WebSocket relay baseline:

const room = createRoom('my-first-room', {
  transport: 'websocket',
  relayUrl: 'ws://localhost:8787',
  presence: { name: 'Alice', color: '#4F46E5' },
});

3) Track Peers with Presence

const presence = room.usePresence();

const unsubscribe = presence.subscribe((peers) => {
  console.log(`Peers online: ${peers.length}`);
});

4) Enable Cursor Sync

const board = document.getElementById('board');
const cursors = room.useCursors();

if (board) {
  cursors.mount(board);
  cursors.render({
    container: board,
    style: 'default',
    showName: true,
  });
}

5) Clean Up on Exit

window.addEventListener('beforeunload', () => {
  unsubscribe();
  void room.disconnect();
});

React Quickstart (Planned Adapter API)

import { RoomfulProvider, usePresence } from '@roomful/react';

function App() {
  return (
    <RoomfulProvider roomId="my-first-room" presence={{ name: 'Alice', color: '#4F46E5' }}>
      <RoomPanel />
    </RoomfulProvider>
  );
}

function RoomPanel() {
  const { others } = usePresence();
  return <p>{others.length} peers in room</p>;
}

Common Next Steps

• Add shared state with room.useState(...)
• Add awareness (typing/focus/selection) with room.useAwareness()
• Add event broadcasting with room.useEvents()

Related Docs

• Installation
• Rooms and transports
• Core API
• Docs index