Quickstart

React Quickstart

Build realtime React applications with Rivet Actors

Steps

Install Dependencies

npm install rivetkit @rivetkit/react

Command Line

Create Backend Actor

Create your actor registry on the 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 },
});

backend/registry.ts

Setup Backend 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;

Create React Frontend

Set up your React application:

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

For detailed information about the React client API, see the React Client API Reference.

Setup Vite Configuration

Configure Vite for development:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    port: 5173,
  },
})

vite.config.ts

Run Your Application

Start both the backend and frontend:

Terminal 1: Start the backend

npx srvx backend/server.ts

bun backend/server.ts

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

Terminal 2: Start the frontend

npx vite

Command Line

Open http://localhost:5173 in your browser. Try opening multiple tabs to see realtime sync in action.

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.