Quickstart

Node.js & Bun Quickstart

Get started with Rivet Actors in Node.js and Bun

Steps

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

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;

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;

Run Server

npx srvx server.ts

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

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

// Get current state
const currentCount = await counter.getCount();
console.log("Current count:", currentCount);

// Listen to realtime 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.

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

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.