Clients - Rivet

Clients

Clients are used to get and communicate with actors from your application. Clients can be created from either your frontend or backend.

Creating a Client

For frontend applications or external services:

import { createClient } from "rivetkit/client";
import type { registry } from "./registry";  // Must use `type`

const client = createClient<typeof registry>();

JavaScript

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

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

Clients include the following options:

const client = createClient<typeof registry>({
	endpoint: "https://api.rivet.dev",
	namespace: "default",
	token: "my-token",
	encoding: "json",  // "json", "cbor", or "bare"
	headers: { "X-Custom-Header": "value" }
});

TypeScript

From your backend server that hosts the registry:

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

const client = createClient<typeof registry>();

TypeScript

From within an actor to communicate with other actors:

import { actor, setup } from "rivetkit";

const counter = actor({
	state: { count: 0 },
	actions: {
		increment: (c) => ++c.state.count
	}
});

const myActor = actor({
	state: {},
	actions: {
		callOtherActor: async (c) => {
			const client = c.client<typeof registry>();
			const counterHandle = client.counter.getOrCreate(["shared"]);
			return await counterHandle.increment();
		}
	}
});

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

TypeScript

Read more about communicating between actors.

Getting an Actor

`getOrCreate`

Returns a handle to an existing actor or creates one if it doesn’t exist:

import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

const counter = actor({
  state: { count: 0 },
  actions: {
    increment: (c, amount: number) => {
      c.state.count += amount;
      return c.state.count;
    }
  }
});

const registry = setup({ use: { counter } });
const client = createClient<typeof registry>();

const counterHandle = client.counter.getOrCreate(["my-counter"]);
const count = await counterHandle.increment(5);

JavaScript

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

// Call actions through the connection
await counter.connection?.increment(5);

Pass initialization data when creating:

import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

const game = actor({
  state: { gameMode: "", maxPlayers: 0 },
  actions: {}
});

const registry = setup({ use: { game } });
const client = createClient<typeof registry>();

const gameHandle = client.game.getOrCreate(["game-123"], {
  createWithInput: { gameMode: "tournament", maxPlayers: 8 }
});

JavaScript

const game = useActor({
  name: "game",
  key: ["game-123"],
  createWithInput: { gameMode: "tournament", maxPlayers: 8 },
});

`get`

Returns a handle to an existing actor or null if it doesn’t exist:

import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

const myActor = actor({
  state: {},
  actions: {
    someAction: (c) => "result"
  }
});

const registry = setup({ use: { myActor } });
const client = createClient<typeof registry>();

const handle = client.myActor.get(["actor-id"]);

if (handle) {
  await handle.someAction();
}

JavaScript

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

// `get` is not currently supported with useActor.
// Use createClient with useMemo instead:

function MyComponent() {
  const client = useMemo(() => createClient<typeof registry>(), []);
  const handle = useMemo(() => client.myActor.get(["actor-id"]), [client]);

  // Use handle to call actions
}

`create`

Creates a new actor, failing if one already exists with that key:

import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

const game = actor({
  state: { gameMode: "" },
  actions: {}
});

const registry = setup({ use: { game } });
const client = createClient<typeof registry>();

const newGame = await client.game.create(["game-456"], {
  input: { gameMode: "classic" }
});

JavaScript

import { createClient } from "rivetkit/client";
import { useMemo, useEffect, useState } from "react";
import type { registry } from "./registry";

// `create` is not currently supported with useActor.
// Use createClient with useMemo instead:

function MyComponent() {
  const client = useMemo(() => createClient<typeof registry>(), []);
  const [handle, setHandle] = useState(null);

  useEffect(() => {
    client.game.create(["game-456"], {
      input: { gameMode: "classic" }
    }).then(setHandle);
  }, [client]);

  // Use handle to call actions
}

`getForId`

Connect to an actor using its internal ID:

import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

const myActor = actor({
  state: {},
  actions: {}
});

const registry = setup({ use: { myActor } });
const client = createClient<typeof registry>();

const actorHandle = client.myActor.getForId("lrysjam017rhxofttna2x5nzjml610");

JavaScript

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

// `getForId` is not currently supported with useActor.
// Use createClient with useMemo instead:

function MyComponent({ actorId }: { actorId: string }) {
  const client = useMemo(() => createClient<typeof registry>(), []);
  const handle = useMemo(() => client.myActor.getForId(actorId), [client, actorId]);

  // Use handle to call actions
}

Prefer using keys over internal IDs for simplicity.

Calling Actions

import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

const counter = actor({
  state: { count: 0 },
  actions: {
    increment: (c, amount: number) => {
      c.state.count += amount;
      return c.state.count;
    },
    getCount: (c) => c.state.count,
    reset: (c) => { c.state.count = 0; }
  }
});

const registry = setup({ use: { counter } });
const client = createClient<typeof registry>();

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

const count = await counterHandle.increment(5);
const value = await counterHandle.getCount();
await counterHandle.reset();

JavaScript

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

// Call actions through the connection
const count = await counter.connection?.increment(5);
const value = await counter.connection?.getCount();
await counter.connection?.reset();

In JavaScript, actions called without connect() are stateless. Each call is independent without a persistent connection. In React, useActor automatically manages a persistent connection.

Connecting to an Actor

For real-time use cases, establish a persistent connection to the actor:

import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

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

const registry = setup({ use: { counter } });
const client = createClient<typeof registry>();

const counterHandle = client.counter.getOrCreate(["live-counter"]);
const conn = counterHandle.connect();

// Listen for events
conn.on("countChanged", (newCount: number) => {
  console.log("Count updated:", newCount);
});

// Call actions through the connection
await conn.increment(1);

JavaScript

const [count, setCount] = useState(0);

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

// Listen for events
counter.useEvent("countChanged", (newCount: number) => {
  setCount(newCount);
});

// Call actions through the connection
await counter.connection?.increment(1);

Subscribing to Events

Listen for events from connected actors:

import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

interface Message {
  from: string;
  text: string;
}

const chatRoom = actor({
  state: { messages: [] as Message[] },
  actions: {
    sendMessage: (c, from: string, text: string) => {
      c.state.messages.push({ from, text });
      c.broadcast("messageReceived", { from, text });
    },
    startGame: (c) => {
      c.broadcast("gameStarted");
    }
  }
});

const registry = setup({ use: { chatRoom } });
const client = createClient<typeof registry>();

const conn = client.chatRoom.getOrCreate(["general"]).connect();

// Listen for events
conn.on("messageReceived", (message: Message) => {
  console.log(`${message.from}: ${message.text}`);
});

// Listen once
conn.once("gameStarted", () => {
  console.log("Game has started!");
});

JavaScript

const [messages, setMessages] = useState<Message[]>([]);

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

// Listen for events (automatically cleaned up on unmount)
chatRoom.useEvent("messageReceived", (message) => {
  setMessages((prev) => [...prev, message]);
});

Full-Stack Type Safety

Import types from your registry for end-to-end type safety:

import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

// Define actors in a shared registry file
const counter = actor({
  state: { count: 0 },
  actions: {
    increment: (c, amount: number) => {
      c.state.count += amount;
      return c.state.count;
    }
  }
});

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

// In your client code, import the registry type
const client = createClient<typeof registry>();

// IDE autocomplete shows available actors and actions
const counterHandle = client.counter.getOrCreate(["my-counter"]);
const count = await counterHandle.increment(5);

JavaScript

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

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

// IDE autocomplete shows available actors and actions
const counter = useActor({ name: "counter", key: ["my-counter"] });
const count = await counter.connection?.increment(5);

Use import type to avoid accidentally bundling backend code in your frontend.

Advanced

Disposing Clients & Connections

Dispose clients to close all connections:

import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

const myActor = actor({
  state: {},
  actions: {}
});

const registry = setup({ use: { myActor } });
const client = createClient<typeof registry>();

// ... use client ...

await client.dispose();

TypeScript

Dispose individual connections when finished:

import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

const myActor = actor({
  state: {},
  actions: {
    action: (c) => "result"
  }
});

const registry = setup({ use: { myActor } });
const client = createClient<typeof registry>();

const actorHandle = client.myActor.getOrCreate(["example"]);
const conn = actorHandle.connect();

const handler = (data: unknown) => console.log(data);

try {
  conn.on("event", handler);
  await conn.action();
} finally {
  await conn.dispose();
}

TypeScript

When using useActor in React, connections are automatically disposed when the component unmounts. No manual cleanup is required.

Connection Parameters

Pass custom data to the actor when connecting:

import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

const chatRoom = actor({
  state: {},
  actions: {}
});

const registry = setup({ use: { chatRoom } });
const client = createClient<typeof registry>();

const chat = client.chatRoom.getOrCreate(["general"], {
  params: {
    userId: "user-123",
    displayName: "Alice"
  }
});

JavaScript

const chat = useActor({
  name: "chatRoom",
  key: ["general"],
  params: {
    userId: "user-123",
    displayName: "Alice"
  },
});

Authentication

Pass authentication tokens when connecting:

import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

const chatRoom = actor({
  state: {},
  actions: {}
});

const registry = setup({ use: { chatRoom } });
const client = createClient<typeof registry>();

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

JavaScript

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

See authentication for more details.

Error Handling

import { actor, setup } from "rivetkit";
import { ActorError, createClient } from "rivetkit/client";

const myActor = actor({
  state: {},
  actions: {
    protectedAction: (c) => "result"
  }
});

const registry = setup({ use: { myActor } });
const client = createClient<typeof registry>();

const actorHandle = client.myActor.getOrCreate(["example"]);
const conn = actorHandle.connect();

conn.on("error", (error: ActorError) => {
  if (error.code === "forbidden") {
    console.log("Redirecting to login");
  }
});

JavaScript (Connection)

import { actor, setup } from "rivetkit";
import { ActorError, createClient } from "rivetkit/client";

const myActor = actor({
  state: {},
  actions: {
    protectedAction: (c) => "result"
  }
});

const registry = setup({ use: { myActor } });
const client = createClient<typeof registry>();

const actorHandle = client.myActor.getOrCreate(["example"]);

try {
  const result = await actorHandle.protectedAction();
} catch (error) {
  if (error instanceof ActorError && error.code === "forbidden") {
    console.log("Redirecting to login");
  }
}

JavaScript (Stateless)

import { ActorError } from "rivetkit/client";

const actor = useActor({ name: "myActor", key: ["id"] });

const handleAction = async () => {
  try {
    await actor.connection?.protectedAction();
  } catch (error) {
    if (error instanceof ActorError && error.code === "forbidden") {
      window.location.href = "/login";
    }
  }
};

See errors for more details.

Actor Resolution

get and getOrCreate return immediately without making a network request. The actor is resolved lazily when you call an action or connect().

To explicitly resolve an actor and get its ID, use resolve():

import { actor, setup } from "rivetkit";
import { createClient } from "rivetkit/client";

const counter = actor({
  state: { count: 0 },
  actions: {}
});

const registry = setup({ use: { counter } });
const client = createClient<typeof registry>();

const handle = client.counter.getOrCreate(["my-counter"]);
const actorId = await handle.resolve();
console.log(actorId); // "lrysjam017rhxofttna2x5nzjml610"

TypeScript

API Reference

createClient - Function to create clients
Client - Client type
ActorHandle - Handle for interacting with actors
ActorConn - Connection to actors
ClientRaw - Raw client interface