rivetkit-client-react

RivetKit React クライアント

@rivetkit/react を使って Rivet Actors に接続する React アプリを構築する際に、このスキルを使用します。

はじめに

1. React クライアントをインストールします（最新：2.1.0-rc.2）

   npm install @rivetkit/[email protected]
   

2. createRivetKit() でフックを作成し、useActor() で接続します。

エラー処理ポリシー

• デフォルトでは、フェイルファストの動作を優先します。
• 絶対に必要な場合を除き、try/catch の使用は避けてください。
• catch を使用する場合は、最低限、ログに記録するなど、エラーを明示的に処理してください。

はじめに

セットアップ方法については、React クイックスタートガイドをご覧ください。

インストール

最小限のクライアント

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

const { useActor } = createRivetKit<typeof registry>({
  endpoint: "https://my-namespace:[email protected]",
});

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

  if (connStatus !== "connected" || !connection) return <div>Connecting...</div>;
  return <button onClick={() => connection.increment(1)}>+</button>;
}

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

ステートレスとステートフル

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 <button onClick={increment}>+</button>;
}

// 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);

アクターの取得

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

const { useActor } = createRivetKit();

function ChatRoom() {
  const room = useActor({ name: "chatRoom", key: ["room-42"] });
  return <div>{room.connStatus}</div>;
}

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

接続パラメーター

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

const { useActor } = createRivetKit();

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

  return <div>{chat.connStatus}</div>;
}

イベントの購読

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

接続のライフサイクル

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

低レベルの HTTP と WebSocket

生の HTTP および WebSocket にアクセスするには、JavaScript クライアントを使用します。

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

バックエンドからの呼び出し

バックエンド（Node.js/Bun）では JavaScript クライアントを使用します。詳しくは、JavaScript クライアントのドキュメントをご覧ください。

エラー処理

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 <button onClick={updateUsername}>Update</button>;
}

概念

キー

キーはアクターインスタンスを一意に識別します。階層的なアドレス指定には、複合キー（配列）を使用します。

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

const { useActor } = createRivetKit<typeof registry>();

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

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

userId にユーザーデータが含まれる場合、"org:${userId}" のような文字列補間でキーを作成しないでください。キーインジェクション攻撃を防ぐため、代わりに配列を使用してください。

環境変数

createRivetKit()（および内部で使用される createClient() インスタンス）は、次の値を自動的に読み取ります。

• RIVET_ENDPOINT
• RIVET_NAMESPACE
• RIVET_TOKEN
• RIVET_RUNNER

未設定の場合、ブラウザーでは window.location.origin + "/api/rivet"、サーバーでは http://127.0.0.1:6420 がデフォルトになります。

エンドポイント形式

エンドポイントでは URL 認証構文を使用できます。

https://namespace:[email protected]

認証情報を含まないエンドポイントを渡し、RIVET_NAMESPACE と RIVET_TOKEN を個別に指定することもできます。サーバーレス環境にデプロイする場合は、アプリの /api/rivet URL を使用してください。詳しくは、エンドポイントをご覧ください。

API リファレンス

パッケージ： @rivetkit/react

• createRivetKit - React 用のフックを作成します
• useActor - アクターインスタンス用のフックです

クライアント以外の情報が必要ですか？

Rivet Actors、レジストリ、またはサーバーサイドの RivetKit について詳しく知りたい場合は、メインスキルを追加してください。

npx skills add rivet-dev/skills

その後、バックエンドに関するガイダンスには rivetkit スキルを使用してください。