Quickstart

Node.js & Bun Quickstart

Create and run your first Rivet Actor with Node.js or Bun, define typed actions, and connect through the JavaScript client.

Prefer to start from a complete project? See the runnable hello-world example.

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

Install Rivet

npm install rivetkit

Create Actors and Start Server

Create a file with your actors, set up the registry, and start the server:

import { actor, setup } from "rivetkit";
import { db } from "rivetkit/db";

export const counter = actor({
	db: db({
		onMigrate: async (db) => {
			await db.execute(
				"CREATE TABLE IF NOT EXISTS counter (id INTEGER PRIMARY KEY CHECK (id = 1), count INTEGER NOT NULL)",
			);
			await db.execute("INSERT OR IGNORE INTO counter (id, count) VALUES (1, 0)");
		},
	}),
	actions: {
		increment: async (c, x: number) => {
			const [{ count }] = await c.db.execute<{ count: number }>(
				"UPDATE counter SET count = count + ? WHERE id = 1 RETURNING count",
				x,
			);
			c.broadcast("newCount", count);
			return count;
		},
	},
});

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

registry.start();

Run Server

Your server is now running on http://localhost:6420. Clients connect directly to the Rivet control plane on this port.

Connect To The Rivet Actor

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

TypeScript

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

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

// 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);

See the JavaScript client documentation for more information.

React

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

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

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

See the React documentation for more information.

Deploy

In development, Rivet runs a local control plane for you and keeps Actor data on your machine.

To scale Rivet in production, pick how much of it you want to run yourself:

If you are running your own nodes, follow the guide for your hosting provider:

Docker Compose

Kubernetes

Virtual Machine

Hetzner

AWS ECS

Railway

Render

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.
Nodes & Node Pools: Run your app as long-lived nodes grouped into node pools.