Quickstart

Node.js & Bun Quickstart

Get started with Rivet Actors in Node.js and Bun

Install Rivet

npm install rivetkit

Command Line

Create an Actor

Create a simple counter actor:

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.ts

Setup Server

Choose your preferred web framework:

import { registry } from "./registry";
import { Hono } from "hono";
import { serve } from "@hono/node-server";

// Start Rivet
const { client } = registry.start();

Run Server

npx tsx --watch server.ts

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

Connect To The Rivet Actor

This code can run either in your frontend or within your backend:

import { createClient } from "rivetkit/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);

client.ts

See the JavaScript client documentation for more information.

Deploy

By default, Rivet stores actor state on the local file system.

To scale Rivet in production, follow a guide to deploy to your hosting provider of choice:

Node.js & Bun Quickstart

Install Rivet

Create an Actor

Setup Server

Run Server

Connect To The Rivet Actor

Deploy

Railway

Kubernetes

AWS ECS

Google Cloud Run

Hetzner

VM & Bare Metal