Chat Room

IMPORTANT: Before doing anything, you MUST read
BASE_SKILL.md
in this skill's directory. It contains essential guidance on debugging, error handling, state management, deployment, and project setup. Those rules and patterns apply to all RivetKit work. Everything below assumes you have already read and understood it.

Working Examples

If you need a reference implementation, read the raw working example code in these templates:

chat-room

Patterns for building a chat room backend with RivetKit: room-scoped actors, persistent message history, and realtime delivery over WebSocket connections.

Starter Code

Start with the working example on GitHub and adapt it. The backend is a single

chatRoom

actor; the frontend is a React app using

@rivetkit/react

(see the React quickstart).

Topic	Summary
Room model	One `chatRoom` actor per room key. The frontend defaults the key to `general` ; typing a different room name connects to a different actor.
History	SQLite `messages` table created in `db({ onMigrate })` , read back with `ORDER BY id ASC` .
Delivery	`sendMessage` inserts the row, then broadcasts a typed `newMessage` event to every connected client.
Identity	None in the example. `sender` is a plain action argument; production should bind identity to the connection.

Room-Per-Actor Model

Each room is one Rivet Actor instance, addressed by key. The client calls

useActor({ name: "chatRoom", key: [roomId] })

, which gets-or-creates the actor for that room. This gives you:

Isolation: each room's history and connections are fully scoped to its key. Switching the room input re-keys the hook and connects to a different actor with separate history.
A single serialized writer: all
```
sendMessage
```
calls for one room run through one actor, so message ordering is consistent without locks. The SQLite
```
AUTOINCREMENT
```
id is the canonical order, which is why
```
getHistory
```
sorts by
```
id
```
rather than by timestamp.
Natural scaling: rooms spread across the cluster independently. A hot room does not slow down other rooms.

Message History Storage

This example stores history in the actor's SQLite database, not in JSON state. Pick based on history size and query needs:

Approach	Use When	Implementation Guidance
SQLite (what this example uses)	Large or long-lived history that needs ordering, caps, pagination, or search	Create the `messages` table in `db({ onMigrate })` , insert with parameterized queries ( `c.db.execute("INSERT ... VALUES (?, ?, ?)", ...)` ), and read with `ORDER BY id ASC` . History survives actor sleep and scales past what you want in memory.
JSON state	Small recent history, for example the last 50 to 100 messages	Push onto a `messages` array in actor state and trim to a cap on every send. Simplest option, but the whole history lives in memory and there is no query layer, so it only fits bounded recent-history use cases.

Broadcast Delivery

New messages reach connected clients through a typed event:

The actor declares

events: { newMessage: event() }

, where

Message

{ sender, text, timestamp }

The
```
sendMessage
```
action builds the message with a server-side
```
Date.now()
```
timestamp, inserts it into the
```
messages
```
table, then calls
```
c.broadcast("newMessage", message)
```
and returns the message to the caller.
Each client subscribes with
```
useEvent("newMessage", ...)
```
and appends to its local list. The sender renders its own message through the same broadcast path as everyone else, so all clients stay on one code path.
History load is connection-gated: once the connection is ready, the client calls
```
getHistory()
```
once to render the backlog, then relies on events for everything after.

Use

c.broadcast(...)

for room-wide messages. For private or per-recipient payloads (such as DMs inside a room), send on the individual connection instead, which is a recommended extension beyond this example.

Typing Indicators And Presence (Extension)

The example does not implement typing indicators, presence, or join/leave handling of any kind. There is no

createConnState

onConnect

, or

onDisconnect

in the code. If you need them, add them as ephemeral connection behavior:

Keep it ephemeral: store the username and typing flag in per-connection state, never in SQLite or persisted actor state. Presence is derived from live connections and should disappear with them.
Broadcast on change only: emit a typing event when a user starts or stops typing, and a presence event from
```
onConnect
```
/
```
onDisconnect
```
, rather than polling or ticking.
Expire on the client: clear a typing indicator after a short client-side timeout so a dropped connection never leaves a stuck "is typing" row.

Per-User Inbox (Extension)

For offline delivery, DMs, unread counts, or notification fanout, add a

userInbox[userId]

actor per user. This is an extension beyond the example:

The room actor forwards each message to the inbox actor of every member via actor-to-actor calls, so users who are not connected to the room still accumulate messages.
The inbox actor owns per-user unread state and serves it when the user comes online, independent of which rooms they are in.
DMs become a degenerate room: either a
```
chatRoom
```
keyed by the sorted pair of user ids, or direct inbox-to-inbox delivery if you do not need shared history semantics.

Actors

Key:
```
chatRoom[roomId]
```
Responsibility: Owns one chat room. Persists the room's message history in its SQLite database and broadcasts each new message to every connected client.
Actions
- ```
sendMessage
```
- ```
getHistory
```
Queues
- None
Events
- ```
newMessage
```
State
- SQLite
- ```
messages
```
  table:
```
id
```
  (autoincrement primary key),
```
sender
```
  ,
```
text
```
  ,
```
timestamp
```

Lifecycle

mermaid

sequenceDiagram
	participant A as Client A
	participant B as Client B
	participant R as chatRoom

	A->>R: connect with key [roomId]
	Note over R: every start runs onMigrate (CREATE TABLE IF NOT EXISTS messages)
	A->>R: getHistory()
	R-->>A: Message[] ordered by id
	B->>R: connect with key [roomId]
	B->>R: getHistory()
	R-->>B: Message[] ordered by id
	A->>R: sendMessage(sender, text)
	Note over R: INSERT row with server timestamp
	R-->>A: newMessage (broadcast)
	R-->>B: newMessage (broadcast)
	A->>R: disconnect
	Note over R: history stays in SQLite for the next connection

Security Checklist

The example is intentionally minimal and skips all of the following. Add them before production:

Auth before join: any client can join any room by knowing its name, and
```
sender
```
is arbitrary client input on every call. Validate a token during connection auth, bind identity to connection state, and check room membership before serving history. Never trust a sender name passed as an action argument.
Message length clamps: the example accepts empty messages and has no length limit. Trim server-side, reject empty text, and clamp to a maximum length.
Per-connection rate limiting: rate limit
```
sendMessage
```
per connection to stop spam and broadcast amplification.
Server-side timestamps and ids: the example already does this correctly.
```
timestamp
```
comes from
```
Date.now()
```
inside the action and
```
id
```
from SQLite
```
AUTOINCREMENT
```
. Keep it that way; never accept client-supplied timestamps or ids.
History caps:
```
getHistory
```
returns every row with no limit. Add a
```
LIMIT
```
plus pagination, and prune or archive old rows so a long-lived room cannot grow unbounded.
Parameterized queries: the example already inserts with
```
?
```
placeholders. Keep all user-supplied text out of SQL string interpolation.

Reference Map

Actors

Access Control
Actions
Actor Keys
Actor Scheduling
Actor Statuses
AI and User-Generated Rivet Actors
Authentication
Communicating Between Actors
Connections
Custom Inspector Tabs
Debugging
Design Patterns
Destroying Actors
Errors
Fetch and WebSocket Handler
Helper Types
Icons & Names
Input Parameters
Lifecycle
Limits
Low-Level HTTP Request Handler
Low-Level KV Storage
Low-Level WebSocket Handler
Metadata
Next.js Quickstart
Node.js & Bun Quickstart
Queues & Run Loops
React Quickstart
Realtime
Rust Quickstart (Preview)
Sandbox Actor
Scaling & Concurrency
Sharing and Joining State
SQLite
SQLite + Drizzle
State & Storage
Testing
Troubleshooting
Types
Vanilla HTTP API
Versions & Upgrades
Workflows

Agent Os

Agent-to-Agent Communication
agentOS vs Sandbox
Authentication
Benchmarks
Configuration
Core Package
Cron Jobs
Deployment
Embedded LLM Gateway
Events
Filesystem
Limitations
LLM Credentials
Multiplayer
Networking & Previews
Overview
Permissions
Persistence & Sleep
Pi
Processes & Shell
Queues
Quickstart
Sandbox Mounting
Security & Auth
Security Model
Sessions
Software
SQLite
System Prompt
Tools
Webhooks
Workflow Automation

Clients

Node.js & Bun
React
Swift
SwiftUI

Connect

Deploy To Amazon Web Services Lambda
Deploying to AWS ECS
Deploying to Cloudflare Workers
Deploying to Freestyle
Deploying to Google Cloud Run
Deploying to Hetzner
Deploying to Kubernetes
Deploying to Railway
Deploying to Rivet Compute
Deploying to Supabase Functions
Deploying to Vercel
Deploying to VMs & Bare Metal

Cookbook

AI Agent
AI Agent Workspaces
Chat Room
Collaborative Text Editor
Cron Jobs and Scheduled Tasks
Database per Tenant
Deploying Rivet in a VPC or Air-Gapped Network
Live Cursors and Presence
Multiplayer Game

General

Actor Configuration
Architecture
Cross-Origin Resource Sharing
Documentation for LLMs & AI
Edge Networking
Endpoints
Environment Variables
HTTP Server
Logging
Pool Configuration
Production Checklist
Registry Configuration
Runtime Modes

Self Hosting

Configuration
Docker Compose
Docker Container
File System
FoundationDB (Enterprise)
Installing Rivet Engine
Kubernetes
Multi-Region
PostgreSQL
Production Checklist
Railway Deployment
Render Deployment
TLS & Certificates

chat-room

NPX Install

Tags

SKILL.md Content

Chat Room

Working Examples

Starter Code

Room-Per-Actor Model

Message History Storage

Broadcast Delivery

Typing Indicators And Presence (Extension)

Per-User Inbox (Extension)

Actors

Lifecycle

Security Checklist

Reference Map

Actors

Agent Os

Clients

Connect

Cookbook

General

Self Hosting