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).

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:

Broadcast Delivery

New messages reach connected clients through a typed event:

• The actor declares events: { newMessage: event() }, where Message is { 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

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 Runtime Socket
• Actor Statuses
• Authentication
• Cloudflare Workers Quickstart
• Communicating Between Actors
• Connections
• Custom Inspector Tabs
• Debugging
• Design Patterns
• Destroying Actors
• Effect.ts Quickstart (Beta)
• Errors
• Fetch and WebSocket Handler
• Helper Types
• Icons & Names
• In-Memory State
• 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 (Beta)
• Scaling & Concurrency
• Schedule & Cron
• Sharing and Joining State
• SQLite
• SQLite + Drizzle
• Supabase Functions Quickstart
• Testing
• Troubleshooting
• Types
• Vanilla HTTP API
• Versions & Upgrades
• Workflows

Cli

• CLI

Clients

• Node.js & Bun
• React
• Rust (Beta)
• Swift
• SwiftUI

Cookbook

• AI Agent
• 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

Deploy

• Container Runner
• 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

General

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

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