1

Install RivetKit

npm install @rivetkit/actor
2

Create an Actor

Create a simple counter actor:

registry.ts
import { actor, setup } from "@rivetkit/actor";

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

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

Setup Server

Choose your preferred web framework:

import { registry } from "./registry";
import { Hono } from "hono";

// Start RivetKit with memory driver (for development)
const { client, serve } = registry.createServer();

// Setup Hono app
const app = new Hono();

// Example API endpoint
app.post("/increment/:name", async (c) => {
	const name = c.req.param("name");

	// Get or create actor and call action
	const counter = client.counter.getOrCreate(name);
	const newCount = await counter.increment(1);

	return c.json({ count: newCount });
});

// Start server with RivetKit
serve(app);

The /registry endpoint is automatically mounted by RivetKit and is required for client communication. When using serve() with Hono, this is handled automatically.

4

Run Server

npx tsx --watch server.ts

Your server is now running at http://localhost:8080

5

Test Your Actor

Test your counter actor using HTTP requests:

// Increment counter
const response = await fetch("http://localhost:8080/increment/my-counter", {
	method: "POST"
});

const result = await response.json();
console.log("Count:", result.count); // 1
6

Deploy

By default, RivetKit stores actor state on the local file system and will not scale in production.

The following providers let you deploy & scale RivetKit:

Rivet provides open-source infrastructure to deploy & scale RivetKit. To deploy to Rivet, provide this config:

rivet.json
{
  "rivetkit": {
    "registry": "src/registry.ts",
    "server": "src/server.ts"
  }
}

And deploy with:

npx rivet-cli@latest deploy

Your endpoint will be available at your Rivet project URL.

​
Configuration Options

​
Connect Frontend To The Rivet Actor

Create a type-safe client to connect from your frontend:

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

// Create typed client
const client = createClient<typeof registry>("http://localhost:8080");

// Use the counter actor directly
const counter = client.counter.getOrCreate(["my-counter"]);

// Call actions
const count = await counter.increment(3);
console.log("New count:", count);

// Get current state
const currentCount = await counter.getCount();
console.log("Current count:", currentCount);

// Listen to real-time events
const connection = counter.connect();
connection.on("countChanged", (newCount) => {
	console.log("Count changed:", newCount);
});

// Increment through connection
await connection.increment(1);

See the JavaScript client documentation for more information.