Registry

Configure and manage your actor registry

The registry is the central configuration hub for your Rivet application. It defines which actors are available and how your application runs.

Basic Setup

Create a registry by importing your actors and using the setup function:

TypeScript

import { setup } from "@rivetkit/actor";
import { counterActor } from "./actors/counter";
import { chatRoomActor } from "./actors/chat-room";

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

Creating Servers

Development Server

For development, create and run a server directly:

TypeScript

import { registry } from "./registry";

// Start a development server
registry.runServer({
  driver: {
    topology: "standalone",
    actor: { type: "memory" },
    manager: { type: "memory" },
  },
});

Production Setup

For production, get the handler and integrate with your framework:

TypeScript

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

// Create server components
const { client, hono, handler, serve } = registry.createServer({
  driver: {
    topology: "partition",
    actor: { type: "redis", url: "redis://localhost:6379" },
    manager: { type: "redis", url: "redis://localhost:6379" },
  },
});

// Use with Hono
const app = new Hono();
app.route("/registry", hono);

// Or use the handler directly
app.all("/registry/*", handler);

// Start the server
serve(app);

Configuration Options

Driver Configuration

The driver configuration determines how actors are stored and managed:

TypeScript

const { client } = registry.createServer({
  driver: {
    // Topology: how actors are distributed
    topology: "standalone", // "standalone" | "partition" | "coordinate"
    
    // Actor storage
    actor: {
      type: "memory", // "memory" | "file-system" | "redis" | "rivet"
      // Additional driver-specific options
    },
    
    // Manager coordination
    manager: {
      type: "memory", // "memory" | "redis" | "rivet"
      // Additional driver-specific options
    },
  },
});

Topology Options

standalone: Single process, good for development
partition: Distributed actors, good for production scaling
coordinate: Peer-to-peer coordination, good for high availability

Storage Drivers

memory: In-memory storage, data lost on restart
file-system: Persistent file-based storage
redis: Redis-backed persistence and coordination
rivet: Rivet platform integration

CORS Configuration

Configure CORS for browser clients:

TypeScript

registry.runServer({
  cors: {
    origin: ["https://myapp.com", "https://staging.myapp.com"],
    credentials: true,
  },
});

Request Limits

Configure request size limits:

TypeScript

registry.runServer({
  maxIncomingMessageSize: 1024 * 1024, // 1MB limit
});

Worker Mode

For distributed topologies, you can create worker instances:

TypeScript

// Manager instance (handles routing)
const { hono: managerHono } = registry.createServer({
  driver: { topology: "partition", /* ... */ },
});

// Worker instance (runs actors)
const { hono: workerHono } = registry.createWorker({
  driver: { topology: "partition", /* ... */ },
});

Type Safety

The registry provides full type safety for your client:

TypeScript

// TypeScript knows about your actors
const counter = client.counter.getOrCreate(["my-counter"]);
const chatRoom = client.chatRoom.getOrCreate(["general"]);

// Action calls are type-checked
const count: number = await counter.increment(5);

Testing Configuration

Use memory drivers for testing:

TypeScript

// test-registry.ts
export const testRegistry = setup({
  use: {
    counter: counterActor,
    chatRoom: chatRoomActor,
  },
});

// In your tests
const { client } = testRegistry.createServer({
  driver: {
    topology: "standalone",
    actor: { type: "memory" },
    manager: { type: "memory" },
  },
});

Environment-Specific Configuration

Use environment variables to configure different environments:

TypeScript

const isProd = process.env.NODE_ENV === "production";
const redisUrl = process.env.REDIS_URL || "redis://localhost:6379";

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

// Environment-specific server creation
export function createAppServer() {
  return registry.createServer({
    driver: isProd
      ? {
          topology: "partition",
          actor: { type: "redis", url: redisUrl },
          manager: { type: "redis", url: redisUrl },
        }
      : {
          topology: "standalone", 
          actor: { type: "memory" },
          manager: { type: "memory" },
        },
    cors: {
      origin: isProd ? "https://myapp.com" : "*",
    },
  });
}

Best Practices

Registry Organization

Keep your registry clean and organized:

TypeScript

// actors/index.ts - Export all actors
export { counterActor } from "./counter";
export { chatRoomActor } from "./chat-room";
export { gameActor } from "./game";

// registry.ts - Import and configure
import { setup } from "@rivetkit/actor";
import * as actors from "./actors";

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

Actor Naming

Use consistent naming conventions:

TypeScript

export const registry = setup({
  use: {
    // Use camelCase for actor names
    counter: counterActor,
    chatRoom: chatRoomActor,
    userProfile: userProfileActor,
    
    // Group related actors with prefixes
    gameSession: gameSessionActor,
    gameLobby: gameLobbyActor,
  },
});

Configuration Management

Separate configuration from registry definition:

TypeScript

// config.ts
export const appConfig = {
  redis: {
    url: process.env.REDIS_URL || "redis://localhost:6379",
  },
  cors: {
    origin: process.env.ALLOWED_ORIGINS?.split(",") || ["*"],
  },
};

// server.ts
import { registry } from "./registry";
import { appConfig } from "./config";

const { serve } = registry.createServer({
  driver: {
    topology: "partition",
    actor: { type: "redis", url: appConfig.redis.url },
    manager: { type: "redis", url: appConfig.redis.url },
  },
  cors: appConfig.cors,
});

serve();