Quickstart

Cloudflare Workers Quickstart

Get started with Rivet Actors on Cloudflare Workers with Durable Objects

Install Rivet

npm install rivetkit @rivetkit/cloudflare-workers

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

Choose your preferred web framework:

import { createHandler } from "@rivetkit/cloudflare-workers";
import { registry } from "./registry";

// The `/rivet` endpoint is automatically exposed here for external clients
const { handler, ActorHandler } = createHandler(registry);
export { handler as default, ActorHandler };

Run Server

Configure your wrangler.json for Cloudflare Workers:

{
  "name": "my-rivetkit-app",
  "main": "src/index.ts",
  "compatibility_date": "2025-01-20",
  "compatibility_flags": ["nodejs_compat"],
  "migrations": [
    {
      "tag": "v1",
      "new_sqlite_classes": ["ActorHandler"]
    }
  ],
  "durable_objects": {
    "bindings": [
      {
        "name": "ACTOR_DO",
        "class_name": "ActorHandler"
      }
    ]
  },
  "kv_namespaces": [
    {
      "binding": "ACTOR_KV",
      "id": "your_namespace_id"
    }
  ]
}

wrangler.json

Start the development server:

wrangler dev

Command Line

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

Test Your Actor

Test your counter actor using HTTP requests:

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

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

Deploy to Cloudflare Workers

Deploy to Cloudflare's global edge network:

wrangler deploy

Command Line

Your actors will now run on Cloudflare's edge with persistent state backed by Durable Objects.

See the Cloudflare Workers deployment guide for detailed deployment instructions and configuration options.

Configuration Options

Connect Frontend To The Rivet Actor

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

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

// Create typed client (use your deployed URL)
const client = createClient<typeof registry>("https://your-app.workers.dev/rivet");

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

client.ts

See the JavaScript client documentation for more information.

Cloudflare Workers mounts the Rivet endpoint on /rivet by default.