Sign In
Concepts

Design Patterns

Common patterns and anti-patterns for building scalable actor systems.

How Actors Scale

Actors are inherently scalable because of how they're designed:

  • Isolated state: Each actor manages its own private data. No shared state means no conflicts and no locks, so actors run concurrently without coordination.
  • Actor-to-actor communication: Actors interact through actions and events, so they don't need to coordinate access to shared data. This makes it easy to distribute them across machines.
  • Small, focused units: Each actor handles a limited scope (a single user, document, or chat room), so load naturally spreads across many actors rather than concentrating in one place.
  • Horizontal scaling: Adding more machines automatically distributes actors across them.

These properties form the foundation for the patterns described below.

Actor Per Entity

The core pattern is creating one actor per entity in your system. Each actor represents a single user, document, chat room, or other distinct object. This keeps actors small, independent, and easy to scale.

Good examples

  • User: Manages user profile, preferences, and authentication
  • Document: Handles document content, metadata, and versioning
  • ChatRoom: Manages participants and message history

Bad examples

  • Application: Too broad, handles everything
  • DocumentWordCount: Too granular, should be part of Document actor

Coordinator & Data Actors

Actors scale by splitting state into isolated entities. However, it's common to need to track and coordinate actors in a central place. This is where coordinator actors come in.

Data actors handle the main logic in your application. Examples: chat rooms, user sessions, game lobbies.

Coordinator actors track other actors. Think of them as an index of data actors. Examples: a list of chat rooms, a list of active users, a list of game lobbies.

Example: Chat Room Coordinator

import { actor } from "rivetkit";

// Data actor: handles messages and connections
const chatRoom = actor({
  state: { messages: [] as { sender: string; text: string }[] },
  actions: {
    sendMessage: (c, sender: string, text: string) => {
      const message = { sender, text };
      c.state.messages.push(message);
      c.broadcast("newMessage", message);
      return message;
    },
    getHistory: (c) => c.state.messages,
  },
});

// Coordinator: indexes chat rooms
const chatRoomList = actor({
  state: { chatRoomIds: [] as string[] },
  actions: {
    createChatRoom: async (c, name: string) => {
      const client = c.client<typeof registry>();
      // Create the chat room actor and get its ID
      const handle = await client.chatRoom.create(name);
      const actorId = await handle.resolve();
      // Track it in the list
      c.state.chatRoomIds.push(actorId);
      return actorId;
    },
    listChatRooms: (c) => c.state.chatRoomIds,
  },
});

export const registry = setup({
  use: { chatRoom, chatRoomList },
});
TypeScript

Sharding

Sharding splits a single actor's workload across multiple actors based on a key. Use this when one actor can't handle all the load or data for an entity.

How it works:

  • Partition data using a shard key (user ID, region, time bucket, or random)
  • Requests are routed to shards based on the key
  • Shards operate independently without coordination

Example: Sharding by Time

import { actor, setup } from "rivetkit";

interface Event {
  type: string;
  url: string;
}

const hourlyAnalytics = actor({
  state: { events: [] as Event[] },
  actions: {
    trackEvent: (c, event: Event) => {
      c.state.events.push(event);
    },
    getEvents: (c) => c.state.events,
  },
});

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

Example: Random Sharding

import { actor, setup } from "rivetkit";

const rateLimiter = actor({
  state: { requests: {} as Record<string, number> },
  actions: {
    checkLimit: (c, userId: string, limit: number) => {
      const count = c.state.requests[userId] ?? 0;
      if (count >= limit) return false;
      c.state.requests[userId] = count + 1;
      return true;
    },
  },
});

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

Choose shard keys that distribute load evenly. Note that cross-shard queries require coordination.

Fan-In & Fan-Out

Fan-in and fan-out are patterns for distributing work and aggregating results.

Fan-Out: One actor spawns work across multiple actors. Use for parallel processing or broadcasting updates.

Fan-In: Multiple actors send results to one aggregator. Use for collecting results or reducing data.

Example: Map-Reduce

import { actor, setup } from "rivetkit";

interface Task {
  id: string;
  data: string;
}

interface Result {
  taskId: string;
  output: string;
}

// Coordinator fans out tasks, then fans in results
const coordinator = actor({
  state: { results: [] as Result[] },
  actions: {
    // Fan-out: distribute work in parallel
    startJob: async (c, tasks: Task[]) => {
      const client = c.client<typeof registry>();
      await Promise.all(
        tasks.map(task => client.worker.getOrCreate(task.id).process(task))
      );
    },
    // Fan-in: collect results
    reportResult: (c, result: Result) => {
      c.state.results.push(result);
    },
    getResults: (c) => c.state.results,
  },
});

const worker = actor({
  state: {},
  actions: {
    process: async (c, task: Task) => {
      const result = { taskId: task.id, output: `Processed ${task.data}` };
      const client = c.client<typeof registry>();
      await client.coordinator.getOrCreate("main").reportResult(result);
    },
  },
});

export const registry = setup({
  use: { coordinator, worker },
});
TypeScript

Integrating With External Databases & APIs

Actors can integrate with external resources like databases or external APIs.

Loading State

Load external data during actor initialization using createVars. This keeps your actor's persisted state clean while caching expensive lookups.

Use this when:

  • Fetching user profiles, configs, or permissions from a database
  • Loading data that changes externally and shouldn't be persisted
  • Caching expensive API calls or computations

Example: Loading User Profile

import { actor, setup } from "rivetkit";

const userSession = actor({
  state: { requestCount: 0 },

  // createVars runs on every wake (after restarts, crashes, or sleep), so
  // external data stays fresh.
  createVars: async (c) => {
    // Load from database on every wake
    const user = await db.users.findById(c.id);
    return { user };
  },

  actions: {
    getProfile: (c) => {
      c.state.requestCount++;
      return c.vars.user;
    },
    updateEmail: async (c, email: string) => {
      c.state.requestCount++;
      await db.users.update(c.id, { email });
      // Refresh cached data
      c.vars.user = await db.users.findById(c.id);
    },
  },
});

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

Syncing State Changes

Use onStateChange to automatically sync actor state changes to external resources. This hook is called whenever the actor's state is modified.

Use this when:

  • You need to mirror actor state in an external database
  • Triggering external side effects when state changes
  • Keeping external systems in sync with actor state

Example: Syncing to Database

import { actor, setup } from "rivetkit";

const userActor = actor({
  state: {
    email: "",
    lastActive: 0,
  },

  onCreate: async (c, input: { email: string }) => {
    // Insert into database on actor creation
    await db.users.insert({
      id: c.id,
      email: input.email,
      createdAt: Date.now(),
    });
  },

  onStateChange: async (c, newState) => {
    // Sync any state changes to database
    await db.users.update(c.id, {
      email: newState.email,
      lastActive: newState.lastActive,
    });
  },

  actions: {
    updateEmail: (c, email: string) => {
      c.state.email = email;
      c.state.lastActive = Date.now();
    },
    getUser: (c) => ({
      email: c.state.email,
      lastActive: c.state.lastActive,
    }),
  },
});

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

onStateChange is called after every state modification, ensuring external resources stay in sync.

Anti-Patterns

"God" Actor

Avoid creating a single actor that handles everything. This defeats the purpose of the actor model and creates a bottleneck.

Problem:

import { actor } from "rivetkit";

// Bad: one actor doing everything
const app = actor({
  state: { users: {}, orders: {}, inventory: {}, analytics: {} },
  actions: {
    createUser: (c, user) => { /* ... */ },
    processOrder: (c, order) => { /* ... */ },
    updateInventory: (c, item) => { /* ... */ },
    trackEvent: (c, event) => { /* ... */ },
  },
});
TypeScript

Solution: Split into focused actors per entity (User, Order, Inventory, Analytics).

Actor-Per-Request

Actors are designed to maintain state across multiple requests. Creating a new actor for each request wastes resources and loses the benefits of persistent state.

Problem:

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

const client = createClient<typeof registry>("http://localhost:8080");

// Bad: creating an actor for each API request
app.post("/process", async (req) => {
  const actor = client.processor.getOrCreate(crypto.randomUUID());
  const result = await actor.process(req.body);
  await actor.destroy();
  return result;
});
TypeScript

Solution: Use actors for entities that persist (users, sessions, documents), not for one-off operations. For stateless request handling, use regular functions.

API Reference

Suggest changes to this page