Quickstart

Node.js & Bun Quickstart

Get started with Rivet Actors in Node.js and Bun

Steps

Add Rivet Skill to Coding Agent (Optional)

If you’re using an AI coding assistant (like Claude Code, Cursor, Windsurf, etc.), add Rivet skills for enhanced development assistance:

npx skills add rivet-dev/skills

Command Line

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

Integrate with your preferred web framework:

import { registry } from "./registry";

// Exposes Rivet API on /api/rivet/ to communicate with actors
export default registry.serve();

No Framework

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

// Build client to communicate with actors (optional)
const client = createClient<typeof registry>();

const app = new Hono();

// Exposes Rivet API to communicate with actors
app.all("/api/rivet/*", (c) => registry.handler(c.req.raw));

// Example endpoint using actors from within your backend (optional)
app.post("/increment/:name", async (c) => {
	const name = c.req.param("name");

	const counter = client.counter.getOrCreate(name);
	const newCount = await counter.increment(1);

	return c.text(`New Count: ${newCount}`);
});

export default app;

Hono

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

// Build client to communicate with actors (optional)
const client = createClient<typeof registry>();

const app = new Elysia()
	// Exposes Rivet API to communicate with actors
	.all("/api/rivet/*", (c) => registry.handler(c.request))
	// Example endpoint using actors from within your backend (optional)
	.get("/increment/:name", async ({ params }) => {
		const counter = client.counter.getOrCreate(params.name);
		const newCount = await counter.increment(1);
		return `New Count: ${newCount}`;
	});

export default app;

Elysia

Run Server

npx srvx server.ts

Node.js

bun server.ts

Bun

deno run --allow-net --allow-read --allow-env server.ts

Deno

Your server is now running. See Server Setup for runtime-specific configurations.

Connect To The Rivet Actor

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

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

TypeScript

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

const client = createClient<typeof registry>();

// Get or create a counter actor for the key "my-counter"
const counter = client.counter.getOrCreate(["my-counter"]);

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

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

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

client.ts

See the JavaScript client documentation for more information.

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

TypeScript

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

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

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

	// Get or create a counter actor for the key "my-counter"
	const counter = useActor({
		name: "counter",
		key: ["my-counter"]
	});

	// Listen to realtime events
	counter.useEvent("newCount", (x: number) => setCount(x));

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

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

Counter.tsx

See the React 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:

Vercel

Railway

Kubernetes

AWS ECS

Google Cloud Run

Hetzner

VM & Bare Metal

Custom Platform

Configuration Options

Server Setup: Different ways to run your server with serve(), handler(), or framework adapters.
Clients: Connect to actors from JavaScript, React, or other platforms.
Authentication: Secure actor connections with custom authentication logic.
CORS: Configure origin restrictions to secure your actors from unauthorized access.
Logging: Configure logging output for debugging and monitoring.
Runtime Modes: Serverless vs runners for different deployment scenarios.