RivetKit React Client

Utilise cette skill lors de la création d'applications React qui se connectent à des Rivet Actors avec @rivetkit/react.

First Steps

Installe le client React (dernière version : 2.2.0)
```
npm install @rivetkit/react@2.2.0
```
Crée des hooks avec createRivetKit() et connecte-toi avec useActor().

Politique de gestion des erreurs

Préfère un comportement fail-fast par défaut.
Évite try/catch sauf si absolument nécessaire.
Si un catch est utilisé, gère l'erreur explicitement, au minimum en la journalisant.

Getting Started

Consulte le guide de démarrage React pour commencer.

Install

Minimal Client

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

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

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

registry.start();

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

// Stateless: utilise createClient pour des appels ponctuels (SSR ou utilitaires)
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 <div>{room.connStatus}</div>;
}

// Pour get/getOrCreate/create/getForId, utilise 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 <div>{chat.connStatus}</div>;
}

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

Utilise le client JavaScript pour l'accès brut HTTP et WebSocket :

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

Utilise le client JavaScript sur ton backend (Node.js/Bun). Consulte la documentation du client JavaScript.

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

Concepts

Keys

Les keys identifient de façon unique les instances d'actor. Utilise des keys composées (tableaux) pour l'adressage hiérarchique :

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

const { useActor } = createRivetKit<typeof registry>("http://localhost:6420");

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

registry.start();

Ne construis pas de keys avec interpolation de chaînes comme "org:${userId}" quand userId contient des données utilisateur. Utilise plutôt des tableaux pour éviter les attaques par injection de key.

Environment Variables

createRivetKit() (et l'instance createClient() sous-jacente) lisent automatiquement :

RIVET_ENDPOINT
RIVET_NAMESPACE
RIVET_TOKEN
RIVET_RUNNER

Par défaut http://localhost:6420 quand non définis. RivetKit fonctionne par défaut sur le port 6420.

Endpoint Format

Les endpoints supportent la syntaxe d'authentification URL :

https://namespace:token@api.rivet.dev

Tu peux aussi passer l'endpoint sans authentification et fournir RIVET_NAMESPACE et RIVET_TOKEN séparément. Pour les déploiements serverless, utilise l'URL /api/rivet de ton application. Consulte Endpoints pour plus de détails.

API Reference

Package: @rivetkit/react

createRivetKit - Crée des hooks pour React
useActor - Hook pour les instances d'actor

Need More Than the Client?

Si tu as besoin de plus d'informations sur les Rivet Actors, les registries, ou RivetKit côté serveur, ajoute la skill principale :

npx skills add rivet-dev/skills

Utilise ensuite la skill rivetkit pour des conseils backend.

rivetkit-client-react