RivetKit JavaScript Client
Use this skill when building JavaScript clients (browser, Node.js, or Bun) that connect to Rivet Actors with rivetkit/client.
First Steps Install the client (latest: 2.0.42-rc.1) npm install rivetkit@2.0.42-rc.1
Create a client with createClient() and call actor actions. Getting Started
See the backend quickstart guide for getting started.
Minimal Client import { createClient } from "rivetkit/client"; import type { registry } from "./registry";
const client = createClient
import { actor, setup } from "rivetkit";
export const counter = actor({ state: { count: 0 }, actions: { increment: (c, x: number) => { c.state.count += x; return c.state.count; }, }, });
export const registry = setup({ use: { counter }, });
Stateless vs Stateful import { createClient } from "rivetkit/client";
const client = createClient(); const handle = client.counter.getOrCreate(["my-counter"]);
// Stateless: each call is independent await handle.increment(1);
// Stateful: keep a connection open for realtime events const conn = handle.connect(); conn.on("count", (value: number) => console.log(value)); await conn.increment(1);
Getting Actors import { createClient } from "rivetkit/client";
const client = createClient(); const room = client.chatRoom.getOrCreate(["room-42"]); const existing = client.chatRoom.get(["room-42"]);
const created = await client.game.create(["game-1"], { input: { mode: "ranked" }, });
const byId = client.chatRoom.getForId("actor-id"); const resolvedId = await room.resolve();
Connection Parameters import { createClient } from "rivetkit/client";
const client = createClient(); const chat = client.chatRoom.getOrCreate(["general"], { params: { authToken: "jwt-token-here" }, });
const conn = chat.connect();
Subscribing to Events import { createClient } from "rivetkit/client";
const client = createClient(); const conn = client.chatRoom.getOrCreate(["general"]).connect(); conn.on("message", (msg: string) => console.log(msg)); conn.once("gameOver", () => console.log("done"));
Connection Lifecycle import { createClient } from "rivetkit/client";
const client = createClient(); const conn = client.chatRoom.getOrCreate(["general"]).connect();
conn.onOpen(() => console.log("connected")); conn.onClose(() => console.log("disconnected")); conn.onError((err) => console.error("error:", err)); conn.onStatusChange((status) => console.log("status:", status));
await conn.dispose();
Low-Level HTTP & WebSocket
For actors that implement onRequest or onWebSocket, call them directly:
import { createClient } from "rivetkit/client";
const client = createClient(); const handle = client.chatRoom.getOrCreate(["general"]);
const response = await handle.fetch("history"); const history = await response.json();
const ws = await handle.websocket("stream"); ws.addEventListener("message", (event) => { console.log("message:", event.data); }); ws.send("hello");
Calling from Backend import { Hono } from "hono"; import { createClient } from "rivetkit/client";
const app = new Hono(); const client = createClient();
app.post("/increment/:name", async (c) => { const counterHandle = client.counter.getOrCreate([c.req.param("name")]); const newCount = await counterHandle.increment(1); return c.json({ count: newCount }); });
Error Handling import { ActorError } from "rivetkit/client"; import { createClient } from "rivetkit/client";
const client = createClient();
try { await client.user.getOrCreate(["user-123"]).updateUsername("ab"); } catch (error) { if (error instanceof ActorError) { console.log(error.code, error.metadata); } }
Concepts Keys
Keys uniquely identify actor instances. Use compound keys (arrays) for hierarchical addressing:
import { createClient } from "rivetkit/client"; import type { registry } from "./registry";
const client = createClient
// Compound key: [org, room] client.chatRoom.getOrCreate(["org-acme", "general"]);
import { actor, setup } from "rivetkit";
export const chatRoom = actor({ state: { messages: [] as string[] }, actions: { getRoomInfo: (c) => ({ org: c.key[0], room: c.key[1] }), }, });
export const registry = setup({ use: { chatRoom }, });
Don't build keys with string interpolation like "org:${userId}" when userId contains user data. Use arrays instead to prevent key injection attacks.
Environment Variables
createClient() automatically reads:
RIVET_ENDPOINT (endpoint) RIVET_NAMESPACE RIVET_TOKEN RIVET_RUNNER
Defaults to window.location.origin + "/api/rivet" in the browser or http://127.0.0.1:6420 on the server when unset.
Endpoint Format
Endpoints support URL auth syntax:
https://namespace:token@api.rivet.dev
You can also pass the endpoint without auth and provide RIVET_NAMESPACE and RIVET_TOKEN separately. For serverless deployments, use your app's /api/rivet URL. See Endpoints for details.
API Reference
Package: rivetkit
See the RivetKit client overview.
createClient - Create a client createEngineDriver - Engine driver DriverConfig - Driver configuration Client - Client type Need More Than the Client?
If you need more about Rivet Actors, registries, or server-side RivetKit, add the main skill:
npx skills add rivet-dev/skills
Then use the rivetkit skill for backend guidance.