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

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";

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.start();

Run Server

Your server is now running on http://localhost:6420. To change the port, pass managerPort in the setup config:

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

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

registry.start();

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.

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.start();

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

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.