npx skills add ...
npx skills add rivet-dev/skills --skill chat-room
npx skills add rivet-dev/skills --skill chat-room
Build a realtime chat room backend with Rivet Actors: one actor per room, SQLite-backed message history, and WebSocket broadcast to every connected client.
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.
If you need a reference implementation, read the raw working example code in these templates:
Patterns for building a chat room backend with RivetKit: room-scoped actors, persistent message history, and realtime delivery over WebSocket connections.
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. |
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:
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.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. |
New messages reach connected clients through a typed event:
events: { newMessage: event() }, where Message is { sender, text, timestamp }.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.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.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.
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:
onConnect / onDisconnect, rather than polling or ticking.For offline delivery, DMs, unread counts, or notification fanout, add a userInbox[userId] actor per user. This is an extension beyond the example:
chatRoom keyed by the sorted pair of user ids, or direct inbox-to-inbox delivery if you do not need shared history semantics.chatRoom[roomId]sendMessagegetHistorynewMessagemessages table: id (autoincrement primary key), sender, text, timestampThe example is intentionally minimal and skips all of the following. Add them before production:
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.sendMessage per connection to stop spam and broadcast amplification.timestamp comes from Date.now() inside the action and id from SQLite AUTOINCREMENT. Keep it that way; never accept client-supplied timestamps or ids.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.? placeholders. Keep all user-supplied text out of SQL string interpolation.