Back to Details

rivetkit-client-javascript

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

RivetKit JavaScript Client

RivetKit JavaScript Client

Use this skill when building JavaScript clients (browser, Node.js, or Bun) that connect to Rivet Actors with 
rivetkit/client
.
当你构建通过
rivetkit/client
连接到Rivet Actors的JavaScript客户端（浏览器、Node.js或Bun环境）时，可以参考本指南。

First Steps

入门步骤

  1. Install the client (latest: 2.0.42)
    bash
    npm install rivetkit@2.0.42
  2. Create a client with 
    createClient()
    and call actor actions.
  1. 安装客户端（最新版本：2.0.42）
    bash
    npm install rivetkit@2.0.42
  2. 使用
    createClient()
    创建客户端并调用Actor操作。

Getting Started

快速开始

See the backend quickstart guide for getting started.
请查看后端快速入门指南来开始使用。

Minimal Client

最简客户端示例

ts
import { createClient } from "rivetkit/client";
import type { registry } from "./registry";

const client = createClient<typeof registry>({
  endpoint: "https://my-namespace:pk_...@api.rivet.dev",
});
const counter = client.counter.getOrCreate(["my-counter"]);
const count = await counter.increment(1);
ts
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 },
});
ts
import { createClient } from "rivetkit/client";
import type { registry } from "./registry";

const client = createClient<typeof registry>({
  endpoint: "https://my-namespace:pk_...@api.rivet.dev",
});
const counter = client.counter.getOrCreate(["my-counter"]);
const count = await counter.increment(1);
ts
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

无状态与有状态

typescript
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);
typescript
import { createClient } from "rivetkit/client";

const client = createClient();
const handle = client.counter.getOrCreate(["my-counter"]);

// 无状态：每次调用相互独立
await handle.increment(1);

// 有状态：保持连接以接收实时事件
const conn = handle.connect();
conn.on("count", (value: number) => console.log(value));
await conn.increment(1);

Getting Actors

获取Actor实例

typescript
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();
typescript
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

连接参数

typescript
import { createClient } from "rivetkit/client";

const client = createClient();
const chat = client.chatRoom.getOrCreate(["general"], {
  params: { authToken: "jwt-token-here" },
});

const conn = chat.connect();
typescript
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

订阅事件

typescript
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"));
typescript
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

连接生命周期

typescript
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();
typescript
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

底层HTTP与WebSocket调用

For actors that implement 
onRequest
or 
onWebSocket
, call them directly:
ts
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");
对于实现了
onRequest
或
onWebSocket
的Actor，可以直接调用这些接口：
ts
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

从后端调用

typescript
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 });
});
typescript
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

错误处理

typescript
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);
  }
}
typescript
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）

Keys uniquely identify actor instances. Use compound keys (arrays) for hierarchical addressing:
ts
import { createClient } from "rivetkit/client";
import type { registry } from "./registry";

const client = createClient<typeof registry>();

// Compound key: [org, room]
client.chatRoom.getOrCreate(["org-acme", "general"]);
ts
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.
键用于唯一标识Actor实例。可以使用复合键（数组形式）实现层级寻址：
ts
import { createClient } from "rivetkit/client";
import type { registry } from "./registry";

const client = createClient<typeof registry>();

// 复合键：[组织, 房间]
client.chatRoom.getOrCreate(["org-acme", "general"]);
ts
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 },
});
当用户数据包含特殊字符时，不要使用字符串拼接（如
"org:${userId}"
）的方式构建键，应使用数组形式以避免键注入攻击。

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.
createClient()
会自动读取以下环境变量：
  • RIVET_ENDPOINT
    （服务端点）
  • RIVET_NAMESPACE
    （命名空间）
  • RIVET_TOKEN
    （令牌）
  • RIVET_RUNNER
    （运行器）
如果未设置这些变量，浏览器环境下默认使用
window.location.origin + "/api/rivet"
，服务器环境下默认使用
http://127.0.0.1:6420
。

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.
端点支持URL认证语法：
https://namespace:token@api.rivet.dev
你也可以传递不带认证信息的端点，然后单独设置
RIVET_NAMESPACE
和
RIVET_TOKEN
。对于无服务器部署，请使用你的应用的
/api/rivet
URL。详情请查看端点文档。

API Reference

API参考

Package: rivetkit
See the RivetKit client overview.
包地址： rivetkit
请查看RivetKit客户端概览。

Need More Than the Client?

如需更多内容？

If you need more about Rivet Actors, registries, or server-side RivetKit, add the main skill:
bash
npx skills add rivet-dev/skills
Then use the 
rivetkit
skill for backend guidance.
如果你需要了解更多关于Rivet Actors、注册中心或服务端RivetKit的内容，请添加主技能包：
bash
npx skills add rivet-dev/skills
然后使用
rivetkit
技能获取后端相关指南。