Quickstart

Node.js & Bun Quickstart

Get started with Rivet Actors in Node.js and Bun

Install Rivet

Command Line

npm install @rivetkit/actor

Create an Actor

Create a simple counter actor:

TypeScript

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

export const counter = actor({
	state: { count: 0 },
	actions: {
		increment: (c, amount: number = 1) => {
			c.state.count += amount;
			c.broadcast("countChanged", c.state.count);
			return c.state.count;
		},
		getCount: (c) => c.state.count,
	},
});

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

Setup Server

Choose your preferred web framework:

import { registry } from "./registry";
import { Hono } from "hono";

// Start Rivet with memory driver (for development)
const { client, serve } = registry.createServer();

// Setup Hono app
const app = new Hono();

// Example API endpoint
app.post("/increment/:name", async (c) => {
	const name = c.req.param("name");

	// Get or create actor and call action
	const counter = client.counter.getOrCreate(name);
	const newCount = await counter.increment(1);

	return c.json({ count: newCount });
});

// Start server with Rivet
serve(app);

import { registry } from "./registry";
import express from "express";

// Start Rivet
const { client, handler } = registry.createServer();

// Setup Express app
const app = express();
app.use(express.json());

// Mount Rivet handler
app.use("/registry", handler);

// Example API endpoints
app.post("/increment/:name", async (req, res) => {
	const { name } = req.params;

      const counter = client.counter.getOrCreate(name);
      const newCount = await counter.increment(1);
      
      res.json({ count: newCount });
});

app.listen(8080, () => {
	console.log("Server running at http://localhost:8080");
});

import { registry } from "./registry";
import { Elysia } from "elysia";

// Start Rivet
const { client, handler } = registry.createServer();

// Setup Elysia app
const app = new Elysia()
	.mount("/registry", handler)
	.post("/increment/:name", async ({ params, body }) => {
		const { name } = params;

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

		return { count: newCount };
	})
	.listen(8080);

console.log("Server running at http://localhost:8080");

Info

The /registry endpoint is automatically mounted by Rivet and is required for client communication. When using serve() with Hono, this is handled automatically.

Run Server

npx tsx --watch server.ts

bun --watch server.ts

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

Test Your Actor

Test your counter actor using HTTP requests:

// Increment counter
const response = await fetch("http://localhost:8080/increment/my-counter", {
	method: "POST"
});

const result = await response.json();
console.log("Count:", result.count); // 1

Deploy

By default, Rivet stores actor state on the local file system and will not scale in production.

The following providers let you deploy & scale Rivet:

For production with Redis storage, install the Redis driver:

Command Line

npm install @rivetkit/redis

Then configure the driver:

TypeScript

import { registry } from "./registry";

const { client, serve } = registry.createServer({
  driver: createRedisDriver()
});

// ... rest of server setup ...

Your backend can now be deployed to your cloud provider of choice.

Configuration Options

Connect Frontend To The Rivet Actor

Create a type-safe client to connect from your frontend:

TypeScript

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

See the JavaScript client documentation for more information.