RivetKit React Client

Use this skill when building React apps that connect to Rivet Actors with @rivetkit/react.

First Steps Install the React client (latest: 2.0.42-rc.1) npm install @rivetkit/react@2.0.42-rc.1

Create hooks with createRivetKit() and connect with useActor(). Getting Started

See the React quickstart guide for getting started.

Install Minimal Client import { createRivetKit } from "@rivetkit/react"; import type { registry } from "./registry";

const { useActor } = createRivetKit({ endpoint: "https://my-namespace:pk_...@api.rivet.dev", });

function Counter() { const { connection, connStatus } = useActor({ name: "counter", key: ["my-counter"] });

if (connStatus !== "connected" || !connection) return

Connecting...

; return ; }

import { actor, setup } from "rivetkit";

export const counter = actor({ state: { count: 0 }, actions: { increment: (c, x: number) => { c.state.count += x; c.broadcast("newCount", c.state.count); return c.state.count; }, }, });

export const registry = setup({ use: { counter }, });

Stateless vs Stateful import { createRivetKit } from "@rivetkit/react";

const { useActor } = createRivetKit();

function Counter() { const counter = useActor({ name: "counter", key: ["my-counter"] });

const increment = async () => { await counter.connection?.increment(1); };

return ; }

// Stateless: use createClient for one-off calls (SSR or utilities) import { createClient } from "rivetkit/client";

const client = createClient(); await client.counter.getOrCreate(["my-counter"]).increment(1);

Getting Actors import { createRivetKit } from "@rivetkit/react"; import { createClient } from "rivetkit/client";

const { useActor } = createRivetKit();

function ChatRoom() { const room = useActor({ name: "chatRoom", key: ["room-42"] }); return

{room.connStatus}

; }

// For get/getOrCreate/create/getForId, use createClient const client = createClient(); const handle = 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 handle.resolve();

Connection Parameters import { createRivetKit } from "@rivetkit/react";

const { useActor } = createRivetKit();

function Chat() { const chat = useActor({ name: "chatRoom", key: ["general"], params: { authToken: "jwt-token-here" }, });

return

{chat.connStatus}

; }

Subscribing to Events import { createRivetKit } from "@rivetkit/react";

const { useActor } = createRivetKit();

function Chat() { const chat = useActor({ name: "chatRoom", key: ["general"] });

chat.useEvent("message", (msg) => { console.log("message:", msg); });

return null; }

Connection Lifecycle import { createRivetKit } from "@rivetkit/react";

const { useActor } = createRivetKit();

function CounterStatus() { const actor = useActor({ name: "counter", key: ["my-counter"] });

if (actor.connStatus === "connected") { console.log("connected"); }

if (actor.error) { console.error(actor.error); }

return null; }

Low-Level HTTP & WebSocket

Use the JavaScript client for raw HTTP and WebSocket access:

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

Use the JavaScript client on your backend (Node.js/Bun). See the JavaScript client docs.

Error Handling import { ActorError } from "rivetkit/client"; import { createRivetKit } from "@rivetkit/react";

const { useActor } = createRivetKit();

function Profile() { const actor = useActor({ name: "user", key: ["user-123"] });

const updateUsername = async () => { try { await actor.connection?.updateUsername("ab"); } catch (error) { if (error instanceof ActorError) { console.log(error.code, error.metadata); } } };

return ; }

Concepts Keys

Keys uniquely identify actor instances. Use compound keys (arrays) for hierarchical addressing:

import { createRivetKit } from "@rivetkit/react"; import type { registry } from "./registry";

const { useActor } = createRivetKit();

function ChatRoom() { const room = useActor({ name: "chatRoom", key: ["org-acme", "general"] }); return

{room.connStatus}

; }

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

createRivetKit() (and the underlying createClient() instance) automatically read:

RIVET_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/react

createRivetKit - Create hooks for React useActor - Hook for actor instances 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.

rivetkit-client-react

安装