Quickstart

Node.js & Bun Quickstart

Get started with Rivet Actors in Node.js and Bun

Install Rivet

Command Line

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 Rivet with file system 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 Rivet
serve(app);

The /registry endpoint is automatically mounted by Rivet 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, Rivet stores actor state on the local file system. To scale Rivet in production, follow a guide to deploy to a hosting provider or integrate a driver:

Hosting Providers

Drivers

Redis

High-performance in-memory data store for production workloads

File System

Simple file-based storage for development and small deployments

Memory

In-memory storage for testing and ephemeral use cases

Build Your Own

Create custom storage drivers for your specific requirements

Configuration Options

Connect Frontend To The Rivet Actor

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

client.ts

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.