Node.js & Bun Quickstart

Install RivetKit

npm install @rivetkit/actor

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

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.

Run Server

npx tsx --watch server.ts

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

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

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 deploy

Your endpoint will be available at your Rivet project URL.

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 deploy

Your endpoint will be available at your Rivet project URL.

Deploy to Cloudflare Workers, install the Cloudflare Workers driver:

npm install @rivetkit/cloudflare-workers

Update your server.ts to support Cloudflare Workers:

import { createServer } from "@rivetkit/cloudflare-workers";
import { Hono } from "hono";
import { registry } from "./registry";

const { client, createHandler } = createServer(registry);

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

// ... etc ...

const { handler, ActorHandler } = createHandler(app);

export { handler as default, ActorHandler };

Update your configuration file to support ACTOR_DO and ACTOR_KV bindings:

wrangler.json

{
  "name": "my-rivetkit-app",
  "main": "src/index.ts",
  "compatibility_date": "2025-01-20",
  "compatibility_flags": ["nodejs_compat"],
  "migrations": [
    {
      "tag": "v1",
      "new_classes": ["ActorHandler"]
    }
  ],
  "durable_objects": {
    "bindings": [
      {
        "name": "ACTOR_DO",
        "class_name": "ActorHandler"
      }
    ]
  },
  "kv_namespaces": [
    {
      "binding": "ACTOR_KV",
      "id": "your_namespace_id"
    }
  ]
}

Finally, deploy:

wrangler deploy

For production with Redis storage, install the Redis driver:

npm install @rivetkit/redis

Then configure the driver:

server.ts

import { registry } from "./registry";

const { client, serve } = registry.createServer({
  driver: createRedisDriver()
});

// ... rest of server setup ...

Your backend can now be deployed to your cloud provider of choice.

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.

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.

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

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

function Counter() {
	const [count, setCount] = useState(0);
	
	const counter = useActor({
		name: "counter",
		key: ["my-counter"]
	});

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

	const increment = async () => {
		await counter.connection?.increment(1);
	};

	return (
		<div>
			<p>Count: {count}</p>
			<button onClick={increment}>Increment</button>
		</div>
	);
}

See the React documentation for more information.

use rivetkit_client::{Client, EncodingKind, GetOrCreateOptions, TransportKind};
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new(
        "http://localhost:8080",
        TransportKind::Sse,
        EncodingKind::Json
    );
    
    // Get or create counter actor
    let options = GetOrCreateOptions::default();
    let counter = client.get("counter", ["my-counter"].into(), options)?
        .connect();
    
    // Subscribe to events
    counter.on_event("countChanged", |args| {
        let count = args[0].as_i64().unwrap();
        println!("Count updated: {}", count);
    }).await;
    
    // Call increment action
    let result = counter.action("increment", vec![json!(1)]).await?;
    println!("New count: {}", result);
    
    Ok(())
}

See the Rust client documentation for more information.

Getting Started

Actors

Integrations

Reference

Node.js & Bun Quickstart

Configuration Options

Connect Frontend To The Rivet Actor

Getting Started

Actors

Integrations

Reference

​Configuration Options

​Connect Frontend To The Rivet Actor

Configuration Options

Connect Frontend To The Rivet Actor