# Node.js & Bun
Source: https://actorcore.org/clients/javascript



The ActorCore JavaScript client allows you to connect to and interact with actors from browser and Node.js applications.

<Info>
  ActorCore is still pre-v1.0. Please help us by report bugs on [GitHub Issues](https://github.com/rivet-gg/actor-core/issues)!
</Info>

## Quickstart

<Steps>
  <Step title="Create a new Node.js project">
    Create a new Node.js project with TypeScript support:

    <CodeGroup>
      ```sh npm
      mkdir my-app
      cd my-app
      npm init -y
      npm pkg set type=module
      ```

      ```sh pnpm
      mkdir my-app
      cd my-app
      pnpm init
      pnpm pkg set type=module
      ```

      ```sh yarn
      mkdir my-app
      cd my-app
      yarn init -y
      yarn pkg set type=module
      ```

      ```sh bun
      mkdir my-app
      cd my-app
      bun init -y
      ```
    </CodeGroup>
  </Step>

  <Step title="Install ActorCore packages">
    Install the ActorCore client and Node.js platform packages:

    <CodeGroup>
      ```sh npm
      npm install actor-core
      ```

      ```sh pnpm
      pnpm add actor-core
      ```

      ```sh yarn
      yarn add actor-core
      ```

      ```sh bun
      bun add actor-core
      ```
    </CodeGroup>
  </Step>

  <Step title="Define your actor">
    Create a file `actors/app.ts` in your project with your actor definition:

    ```typescript actors/app.ts
    import { actor, setup } from "actor-core";

    // Create actor
    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;
        }
      }
    });

    // Create the application
    export const app = setup({
      actors: { counter },
      cors: { origin: "*" } // Configure CORS for your production domains in production
    });

    // Export app type for client usage
    export type App = typeof app;
    ```
  </Step>

  <Step title="Create your client">
    Create a file `src/client.ts` in your project to connect to your actor:

    ```typescript src/client.ts
    import { createClient } from "actor-core/client";
    import type { App } from "../actors/app";

    async function main() {
      // Replace with your endpoint URL after deployment
      const client = createClient<App>("http://localhost:6420");

      // Get or create an actor instance
      const counter = await client.counter.get();

      // Subscribe to events
      counter.on("newCount", (count: number) => console.log("Event:", count));

      // Call an action
      const out = await counter.increment(5);
      console.log("Action:", out);

      // Clean up when done
      await counter.dispose();
    }

    main().catch(console.error);
    ```
  </Step>

  <Step title="Start your ActorCore development server">
    Launch the development server with:

    <CodeGroup>
      ```sh npm
      npx @actor-core/cli@latest dev actors/app.ts
      ```

      ```sh pnpm
      pnpm exec @actor-core/cli@latest dev actors/app.ts
      ```

      ```sh yarn
      yarn @actor-core/cli@latest dev actors/app.ts
      ```

      ```sh bun
      bunx @actor-core/cli@latest dev actors/app.ts
      ```
    </CodeGroup>

    This will automatically start your app and open the studio in your browser. The studio supports hot-reloading, state inspection, visual RPC testing, and more debugging tools.

    ![ActorCore Studio](https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/screenshots/studio/simple.png)
  </Step>

  <Step title="Run your client">
    In a separate terminal, run your client code:

    <CodeGroup>
      ```sh npm
      npx tsx src/client.ts
      ```

      ```sh pnpm
      pnpm exec tsx src/client.ts
      ```

      ```sh yarn
      yarn tsx src/client.ts
      ```

      ```sh bun
      bun run src/client.ts
      ```
    </CodeGroup>

    You should see output like:

    ```
    Event: 5
    Action: 5
    ```

    Run it again to see the state update.
  </Step>

  <Step title="Deploy your ActorCore app">
    Now that you have your project running, deploy your application to one of these platforms:

    <CardGroup cols={2}>
      <Card title="Rivet" href="/platforms/rivet" />

      <Card title="Cloudflare Workers" href="/platforms/cloudflare-workers" />

      <Card title="Bun" href="/platforms/bun" />

      <Card title="Node.js" href="/platforms/nodejs" />
    </CardGroup>
  </Step>
</Steps>

## Next Steps

See the [Interacting with Actors](/concepts/interacting-with-actors) documentation for information on how to use the client.


# Rust
Source: https://actorcore.org/clients/rust



The ActorCore Rust client provides a way to connect to and interact with actors from Rust applications.

<Info>
  ActorCore is still pre-v1.0. Please help us by report bugs on [GitHub Issues](https://github.com/rivet-gg/actor-core/issues)!
</Info>

## Quickstart

<Steps>
  <Step title="Create a new Rust project">
    Create a new Rust project:

    ```sh
    cargo new my-app
    cd my-app
    ```
  </Step>

  <Step title="Add dependencies">
    Add ActorCore client & related dependencies to your project:

    ```sh
    cargo add actor-core-client
    cargo add serde_json
    cargo add tokio --features full
    ```
  </Step>

  <Step title="Define your actor">
    Create a file `actors/app.ts` in your project with your actor definition:

    ```typescript actors/app.ts
    import { actor, setup } from "actor-core";

    // Create actor
    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;
        }
      }
    });

    // Create the application
    export const app = setup({
      actors: { counter },
      cors: { origin: "*" } // Configure CORS for your production domains in production
    });

    // Export app type for client usage
    export type App = typeof app;
    ```
  </Step>

  <Step title="Create your client">
    Modify `src/main.rs` to connect to your actor:

    ```rust src/main.rs
    use actor_core_client::{Client, GetOptions, TransportKind, EncodingKind};
    use serde_json::json;
    use std::time::Duration;

    #[tokio::main]
    async fn main() -> Result<(), Box<dyn std::error::Error>> {
        // Replace with your endpoint URL after deployment
        let client = Client::new(
            "http://localhost:6420".to_string(),
            TransportKind::WebSocket,
            EncodingKind::Cbor,
        );
        
        // Get or create an actor instance
        let options = GetOptions::default();
        let counter = client.get("counter", options).await?;
        
        // Subscribe to events
        counter.on_event("newCount", |args| {
            let count = args[0].as_i64().unwrap();
            println!("Event: {}", count);
        }).await;
        
        // Call an action
        let result = counter.action("increment", vec![json!(5)]).await?;
        println!("Action: {}", result);
        
        // Wait to receive events
        tokio::time::sleep(Duration::from_secs(1)).await;
        
        Ok(())
    }
    ```
  </Step>

  <Step title="Start your ActorCore development server">
    Launch the development server with:

    <CodeGroup>
      ```sh npm
      npx @actor-core/cli@latest dev actors/app.ts
      ```

      ```sh pnpm
      pnpm exec @actor-core/cli@latest dev actors/app.ts
      ```

      ```sh yarn
      yarn @actor-core/cli@latest dev actors/app.ts
      ```

      ```sh bun
      bunx @actor-core/cli@latest dev actors/app.ts
      ```
    </CodeGroup>

    This will automatically start your app and open the studio in your browser. The studio supports hot-reloading, state inspection, visual RPC testing, and more debugging tools.

    ![ActorCore Studio](https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/screenshots/studio/simple.png)
  </Step>

  <Step title="Run your client">
    In a separate terminal, run your client code:

    ```sh
    cargo run
    ```

    You should see output like:

    ```
    Event: 5
    Action: 5
    ```

    Run it again to see the state update.
  </Step>

  <Step title="Deploy your ActorCore app">
    Now that you have your project running, deploy your application to one of these platforms:

    <CardGroup cols={2}>
      <Card title="Rivet" href="/platforms/rivet" />

      <Card title="Cloudflare Workers" href="/platforms/cloudflare-workers" />

      <Card title="Bun" href="/platforms/bun" />

      <Card title="Node.js" href="/platforms/nodejs" />
    </CardGroup>
  </Step>
</Steps>

## Next Steps

<CardGroup>
  <Card title="Overview" href="/concepts/overview" icon="square-plus" horizontal={true} />

  <Card title="Interacting with Actors" href="/concepts/interacting-with-actors" icon="square-plus" horizontal={true} />

  <Card title="Actions" href="/concepts/actions" icon="bolt" horizontal={true} />

  <Card title="State" href="/concepts/state" icon="floppy-disk" horizontal={true} />
</CardGroup>


# Actions
Source: https://actorcore.org/concepts/actions



Actions are how clients & other actors communicate with actors. Actions are defined as functions in the actor configuration and can be called from clients.

<Tip>
  **Performance**

  Actions are very lightweight. They can be called hundreds of times per second to send realtime data to the
  actor.
</Tip>

## Writing Actions

Actions are defined in the `actions` object when creating an actor:

```typescript
import { actor } from "actor-core";

const mathUtils = actor({
  state: {},
  actions: {
    // This is an action
    multiplyByTwo: (c, x) => {
      return x * 2;
    }
  }
});
```

Each action receives a context object (commonly named `c`) as its first parameter, which provides access to state, connections, and other utilities. Additional parameters follow after that.

### Private Helper Functions

You can define helper functions outside the actions object to keep your code organized. These functions cannot be called directly by clients:

```typescript
import { actor } from "actor-core";

// Private helper function - not callable by clients
const calculateFee = (amount) => {
  return amount * 0.05;
};

const paymentProcessor = actor({
  state: { 
    transactions: [] 
  },
  actions: {
    // Public action - callable by clients
    processPayment: (c, amount) => {
      const fee = calculateFee(amount);
      // Process payment logic...
      c.state.transactions.push({ amount, fee });
      return { amount, fee };
    }
  }
});
```

### Streaming Return Data

Actions have a single return value. To stream realtime data in response to an action, use [events](/concepts/events).

## Calling Actions

Calling actions from the client is simple:

```typescript
import { createClient } from "actor-core/client";
import type { App } from "./src/index";

const client = createClient<App>("http://localhost:6420");
const counter = await client.counter.get();
const result = await counter.increment(42);
console.log(result); // The value returned by the action
```

<Note>
  Calling actions from the client are async and require an `await`, even if the action itself is not async.
</Note>

### Type Safety

The actor client includes type safety out of the box. When you use `createClient<App>()`, TypeScript automatically infers action parameter and return types:

<CodeGroup>
  ```typescript src/index.ts
  import { setup } from "actor-core";

  // Create simple counter
  const counter = actor({
    state: { count: 0 },
    actions: {
      increment: (c, count: number) => {
        c.state.count += count;
        return c.state.count;
      }
    }
  });

  // Create and export the app
  const app = setup({
    actors: { counter }
  });

  export type App = typeof app;
  ```

  ```typescript client.ts
  import { createClient } from "actor-core/client";
  import type { App } from "./src/index";

  const client = createClient<App>("http://localhost:6420");

  // Type-safe client usage
  const counter = await client.counter.get();
  await counter.increment(123); // OK
  await counter.increment("non-number type"); // TypeScript error
  await counter.nonexistentMethod(123); // TypeScript error
  ```
</CodeGroup>

## Error Handling

Actors provide robust error handling out of the box for actions.

### User Errors

`UserError` can be used to return rich error data to the client. You can provide:

* A human-readable message
* A machine-readable code that's useful for matching errors in a try-catch (optional)
* A metadata object for providing richer error context (optional)

For example:

<CodeGroup>
  ```typescript actor.ts
  import { actor, UserError } from "actor-core";

  const user = actor({
    state: { users: [] },
    actions: {
      registerUser: (c, username) => {
        // Validate username
        if (username.length > 32) {
          // Throw a simple error with a message
          throw new UserError("Invalid username", {
            code: "invalid_username",
            meta: {
              maxLength: 32
            }
          });
        }
        
        // Rest of the user registration logic...
      }
    }
  });
  ```

  ```typescript client.ts
  try {
    await userActor.registerUser("extremely_long_username_that_exceeds_limit");
  } catch (error) {
    console.log("Message", error.message); // "Invalid username"
    console.log("Code", error.code); // "invalid_username"
    console.log("Metadata", error.metadata); // { maxLength; 32 }
  }
  ```
</CodeGroup>

{/* Read the documentation for `UserError` [here](https://jsr.io/@rivet-gg/actor/doc/~/UserError). */}

### Internal Errors

All other errors will return an error with the code `internal_error` to the client. This helps keep your application secure, as errors can sometimes expose sensitive information.

## Schema Validation

Data schemas are not validated by default. For production applications, use a library like [zod](https://zod.dev/) to validate input types.

For example, to validate action parameters:

```typescript
import { actor, UserError } from "actor-core";
import { z } from "zod";

// Define schema for action parameters
const IncrementSchema = z.object({
  count: z.number().int().positive()
});

const counter = actor({
  state: { count: 0 },
  actions: {
    increment: (c, params) => {
      // Validate parameters
      try {
        const { count } = IncrementSchema.parse(params);
        c.state.count += count;
        return c.state.count;
      } catch (err) {
        throw new UserError("Invalid parameters", { 
          code: "invalid_params",
          meta: { errors: err.errors }
        });
      }
    }
  }
});
```

<Note>
  Native runtime type validation is coming soon to ActorCore.
</Note>

## Authentication

By default, clients can call all actions on an actor without restriction. Make sure to implement authentication if needed. Documentation on authentication is available [here](/concepts/authentication).

## Using `ActionContext` Type Externally

When writing complex logic for actions, you may want to extract parts of your implementation into separate helper functions. When doing this, you'll need a way to properly type the context parameter.

ActorCore provides the `ActionContextOf` utility type for exactly this purpose:

```typescript
import { actor, ActionContextOf } from "actor-core";

const counter = actor({
  state: { count: 0 },
  
  actions: {
    increment: (c) => {
      return incrementCount(c);
    }
  }
});

// Simple helper function with typed context
function incrementCount(c: ActionContextOf<typeof counter>) {
  c.state.count += 1;
  return c.state.count;
}
```

See [Helper Types](/concepts/types) for more details on using `ActionContextOf` and other type utilities.


# Authentication
Source: https://actorcore.org/concepts/authentication



Authentication can be handled through the `onBeforeConnect` or `createConnState` lifecycle hook, which acts as middleware before allowing clients to interact with your actor.

## Using `onBeforeConnect` or `createConnState`

The `onBeforeConnect` and `createConnState` hook is called whenever a new client attempts to connect to your actor. It receives a context object that contains the client's connection parameters. `createConnState` should return an object that will become the connection state.

Throwing an error in `onBeforeConnect` or `createConnState` will abort the connection.

Here's a basic example:

```typescript
import { actor } from "actor-core";

const exampleActor = actor({
  state: {
    // Actor state...
  },
  
  createConnState: async (c, { params }) => {
    // Verify the token with your authentication system
    const userData = await myValidateAuthToken(params.authToken);
    if (!userData) {
      throw new Error('Invalid auth token');
    }

    // Return the user data to store with the connection
    return {
      userId: userData.id,
      role: userData.role
    };
  },
  
  actions: {
    // Actor actions...
  }
});
```

## Accessing Connection State

After authentication, you can access the connection state in any action through the context object:

```typescript
import { actor } from "actor-core";

const authenticatedActor = actor({
  state: {
    // Actor state...
  },
  
  createConnState: (c) => {
    // Authentication logic...
    return {
      userId: "user_123",
      role: "admin"
    };
  },
  
  actions: {
    exampleAdminCommand: (c) => {
      // Example of validating admin access
      if (c.conn.state.role !== 'admin') {
        throw new Error('User must be an admin');
      }

      // Admin-only functionality...
      return { success: true };
    }
  }
});
```

## Integration Examples

### With API Server Authentication

```typescript
import { actor } from "actor-core";

const apiAuthenticatedActor = actor({
  state: {
    // Actor state...
  },
  
  createConnState: async (c, { params }) => {
    // Validate API key with your server
    const response = await fetch('https://api.yourserver.com/validate', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${params.apiKey}`
      }
    });

    if (!response.ok) {
      throw new Error('Invalid API key');
    }

    const user = await response.json();

    return {
      userId: user.id
    };
  },
  
  actions: {
    // Actor actions...
  }
});
```

When authentication fails, throwing an error in `createConnState` will prevent the connection from being established, and the client will receive the error message.

### With JWT Authentication

```typescript
import { actor } from "actor-core";
import jwt from "jsonwebtoken";

const JWT_SECRET = process.env.JWT_SECRET;

const jwtAuthenticatedActor = actor({
  state: {
    // Actor state...
  },
  
  createConnState: (c, { params }) => {
    try {
      // Verify JWT token
      const decoded = jwt.verify(params.jwt, JWT_SECRET);
      
      return {
        userId: decoded.sub,
        permissions: decoded.permissions
      };
    } catch (error) {
      throw new Error('Invalid or expired JWT token');
    }
  },
  
  actions: {
    secureAction: (c, data) => {
      // Check permissions before proceeding
      if (!c.conn.state.permissions.includes('write')) {
        throw new Error('Permission denied: requires write access');
      }
      
      // Perform action with data...
      return { success: true };
    }
  }
});
```


# Connections
Source: https://actorcore.org/concepts/connections



Connections represent client connections to your actor. They provide a way to handle client authentication, manage connection-specific data, and control the connection lifecycle.

## Parameters

When clients connect to an actor, they can pass connection parameters that are handled during the connection process.

For example:

<CodeGroup>
  ```typescript actor.ts
  import { actor } from "actor-core";

  const gameRoom = actor({
    state: {},
    
    // Handle connection setup
    createConnState: (c, { params }) => {
      // Validate authentication token
      const authToken = params.authToken;
      
      if (!authToken || !validateToken(authToken)) {
        throw new Error("Invalid auth token");
      }
      
      // Create connection state
      return { userId: getUserIdFromToken(authToken), role: "player" };
    },
    
    actions: {
      // ...
    }
  });
  ```

  ```typescript client.ts
  import { createClient } from "actor-core/client";
  import type { App } from "./src/index";

  const client = createClient<App>("http://localhost:6420");
  const gameRoom = await client.gameRoom.get({
    params: { authToken: "supersekure" }
  });
  ```
</CodeGroup>

## Connection State

There are two ways to define an actor's connection state:

### Method 1: `ConnState` constant

```typescript
import { actor } from "actor-core";

const chatRoom = actor({
  state: { messages: [] },
  
  // Define default connection state as a constant
  connState: {
    role: "guest",
    joinedAt: 0
  },
  
  onConnect: (c) => {
    // Update join timestamp when a client connects
    c.conn.state.joinedAt = Date.now();
  },
  
  actions: {
    // ...
  }
});
```

### Method 2: `createConnState` function

The data returned from `createConnState` is used as the initial state of the connection. The connection state can be accessed through `conn.state`.

```typescript
import { actor } from "actor-core";

const chatRoom = actor({
  state: { messages: [] },
  
  // Create connection state dynamically
  createConnState: (c) => {
    // Validate any connection parameters
    // ...
    
    // Return the connection state
    return { 
      userId: generateUserId(),
      role: "guest",
      joinedAt: Date.now()
    };
  },
  
  actions: {
    sendMessage: (c, message) => {
      const username = c.conn.state.userId;
      c.state.messages.push({ username, message });
      c.broadcast("newMessage", { username, message });
    }
  }
});
```

## Lifecycle Hooks

The connection lifecycle has several hooks:

* `onBeforeConnect`: Called before a client connects, returns the connection state
* `onConnect`: Called when a client successfully connects
* `onDisconnect`: Called when a client disconnects

See the documentation on [Actor Lifecycle](/concepts/lifecycle) for more details.

## Connection List

All active connections can be accessed through the context object's `conns` property. This is an array of all current connections.

This is frequently used with `conn.send(name, event)` to send messages directly to clients.

For example:

```typescript
import { actor } from "actor-core";

const chatRoom = actor({
  state: { users: {} },
  
  actions: {
    sendDirectMessage: (c, recipientId, message) => {
      // Find the recipient's connection
      const recipientConn = c.conns.find(conn => conn.state.userId === recipientId);
      
      if (recipientConn) {
        // Send a private message to just that client
        recipientConn.send('directMessage', {
          from: c.conn.state.userId,
          message: message
        });
      }
    }
  }
});
```

## Disconnecting clients

Connections can be disconnected from within an action:

```typescript
import { actor } from "actor-core";

const secureRoom = actor({
  state: {},
  
  actions: {
    kickUser: (c, targetUserId, reason) => {
      // Find the connection to kick
      const targetConn = c.conns.find(conn => conn.state.userId === targetUserId);
      
      if (targetConn) {
        // Disconnect with a reason
        targetConn.disconnect(reason || "Kicked by admin");
      }
    }
  }
});
```

<Tip>
  If you need to wait for the disconnection to complete, you can use `await`:

  ```typescript
  await c.conn.disconnect('Too many requests');
  ```

  This ensures the underlying network connections close cleanly before continuing.
</Tip>

## Offline & Auto-Reconnection

See [Interacting with Actors](/concepts/interacting-with-actors#offline-and-auto-reconnection) for details on reconnection behavior.


# Cross-Origin Resource Sharing
Source: https://actorcore.org/concepts/cors



Cross-Origin Resource Sharing (CORS) is a security mechanism that allows a web application running at one origin to access resources from a different origin. Without CORS, browsers block cross-origin HTTP requests by default as a security measure.

You'll need to configure CORS when:

* **Local Development:** You're developing locally and your client runs on a different port than your actor service
* **Different Domain:** Your frontend application is hosted on a different domain than your actor service

## Example

```ts
import { setup } from "actor-core";
import counter from "./counter";

const app = setup({
  actors: { counter },
  // Change this to match your frontend's origin
  cors: { origin: "https://yourdomain.com" }
});
```

## Options

### `origin`

`string | string[] | (origin:string, c:Context) => string` (optional)

Specifies which domains can access your resources. Options:

* Single domain: `"https://example.com"`
* Multiple domains: `["https://app.com", "https://admin.com"]`
* Dynamic validation: `(origin) => origin.endsWith('.example.com') ? origin : null`
* All domains (not recommended for production): `"*"` (default)

### `allowMethods`

`string[]` (optional)

HTTP methods clients are allowed to use when accessing your resources. Default includes all standard methods: `['GET', 'HEAD', 'PUT', 'POST', 'DELETE', 'PATCH']`.

### `allowHeaders`

`string[]` (optional)

Custom HTTP headers clients can send in requests. Empty by default `[]`. Common examples:

* `["Content-Type", "Authorization", "X-API-Key"]`

### `maxAge`

`number` (optional)

How long browsers should cache CORS response (in seconds). Higher values improve performance by reducing preflight requests.

### `credentials`

`boolean` (optional)

Whether requests can include user credentials like cookies or HTTP authentication. Must specify exact origins when enabled (cannot use with `origin: "*"`).

### `exposeHeaders`

`string[]` (optional)

Server headers that browsers are allowed to access. Empty by default `[]`. Example:

* `["Content-Length", "X-Request-Id"]`


# Events
Source: https://actorcore.org/concepts/events



Events are used for clients to receive realtime data from actors.

<Info>Events are used for actors to publish updates to clients. Clients call actions to communicate with the actor.</Info>

## Publishing from actors

Actors can publish events to clients using `c.broadcast` and `conn.send`.

### Broadcasting events

Actors can publish events to all connected clients with `c.broadcast(name, data)`. For example:

<CodeGroup>
  ```typescript chat_room.ts
  import { actor } from "actor-core";

  const chatRoom = actor({
    state: {},
    actions: {
      sendMessage: (c, message) => {
        c.broadcast('newMessage', { message });
      }
    }
  });
  ```

  ```typescript client.ts
  import { createClient } from "actor-core/client";
  import type { App } from "./src/index";

  const client = createClient<App>("http://localhost:6420");
  const chatRoom = await client.chatRoom.get();
  await chatRoom.sendMessage('Hello, world!');
  ```
</CodeGroup>

### Sending events to specific connections

Actors can send messages to specific client connections. All connections are available through the context object. For example:

<CodeGroup>
  ```typescript chat_room.ts
  import { actor } from "actor-core";

  const chatRoom = actor({
    state: {},
    actions: {
      sendPrivateMessage: (c, connId, message) => {
        const conn = c.conns.find(conn => conn.id === connId);
        if (conn) {
          conn.send('newMessage', { message });
        }
      }
    }
  });
  ```

  ```typescript client.ts
  import { createClient } from "actor-core/client";
  import type { App } from "./src/index";

  const client = createClient<App>("http://localhost:6420");
  const chatRoom = await client.chatRoom.get();
  await chatRoom.sendPrivateMessage(123, 'Hello, world!');
  ```
</CodeGroup>

## Subscribing from clients

Clients can subscribe to events from actors using `on` and `once`.

### `on(eventName, callback)`

{/* [Documentation](https://jsr.io/@rivet-gg/actor-client/doc/~/ActorHandleRaw.prototype.on.html) */}

Clients can subscribe to events that will happen repeatedly using `actor.on(name, callback)`. For example:

<CodeGroup>
  ```typescript client.ts
  import { createClient } from "actor-core/client";
  import type { App } from "./src/index";

  const client = createClient<App>("http://localhost:6420");
  const chatRoom = await client.chatRoom.get();

  chatRoom.on('newMessage', ({ message }) => {
    console.log('Message', message);
  });
  ```

  ```typescript chat_room.ts
  import { actor } from "actor-core";

  const chatRoom = actor({
    state: {},
    actions: {
      sendMessage: (c, message) => {
        c.broadcast('newMessage', { message });
      }
    }
  });
  ```
</CodeGroup>

### `once(eventName, callback)`

{/* [Documentation](https://jsr.io/@rivet-gg/actor-client/doc/~/ActorHandleRaw.prototype.once.html) */}

Clients can listen for an event only one time with `actor.once(name, callback)`. For example:

<CodeGroup>
  ```typescript client.ts
  import { createClient } from "actor-core/client";
  import type { App } from "./src/index";

  const client = createClient<App>("http://localhost:6420");
  const chatRoom = await client.chatRoom.get();

  chatRoom.once('joinRequestApproved', () => {
    // This will only be called once
    console.log('Join request accepted');
  });

  await chatRoom.requestJoin();
  ```

  ```typescript chat_room.ts
  import { actor } from "actor-core";

  const chatRoom = actor({
    state: {
      pendingJoinRequests: []
    },
    actions: {
      requestJoin: (c) => {
        // ...add to pending requests...
      },
      approveJoinRequest: (c, connId) => {
        const conn = c.conns.find(conn => conn.id === connId);
        if (conn) {
          conn.send('joinRequestApproved');
        }
      }
    }
  });
  ```
</CodeGroup>

## Connections

Connections are used to communicate with clients from the actor.

Read more about connections [here](/concepts/connections).


# External SQL Database
Source: https://actorcore.org/concepts/external-sql



While actors can serve as a complete database solution, they can also complement your existing databases. For example, you might use actors to handle frequently-changing data that needs real-time access, while keeping less frequently accessed data in your traditional database.

Actors can be used with common SQL databases, such as PostgreSQL and MySQL.

## Libraries

To facilitate interaction with SQL databases, you can use either ORM libraries or raw SQL drivers. Each has its own use cases and benefits:

* **ORM Libraries**: Type-safe and easy way to interact with your database

  * [Drizzle](https://orm.drizzle.team/)
  * [Prisma](https://www.prisma.io/)

* **Raw SQL Drivers**: Direct access to the database for more flexibility

  * [PostgreSQL](https://node-postgres.com/)
  * [MySQL](https://github.com/mysqljs/mysql)

## Hosting Providers

There are several options for places to host your SQL database:

* [Supabase](https://supabase.com/)
* [Neon](https://neon.tech/)
* [PlanetScale](https://planetscale.com/)
* [AWS RDS](https://aws.amazon.com/rds/)
* [Google Cloud SQL](https://cloud.google.com/sql)

## Example

Here's a basic example of how you might set up a connection to a PostgreSQL database using the `pg` library:

```typescript actor.ts
import { actor } from "actor-core";
import { Pool } from "pg";

// Create a database connection pool
const pool = new Pool({
  user: "your_db_user",
  host: "localhost",
  database: "your_db_name",
  password: "your_db_password",
  port: 5432,
});

// Create the actor
const databaseActor = actor({
  state: {
    // Local state if needed
    lastQueryTime: 0
  },
  
  // Initialize any resources
  onStart: (c) => {
    console.log("Database actor started");
  },
  
  // Clean up resources if needed
  onShutdown: async (c) => {
    await pool.end();
    console.log("Database connections closed");
  },
  
  // Define actions
  actions: {
    // Example action to fetch data from database
    fetchData: async (c) => {
      try {
        const result = await pool.query("SELECT * FROM your_table");
        c.state.lastQueryTime = Date.now();
        return result.rows;
      } catch (error) {
        console.error("Error fetching data:", error);
        throw new Error("Failed to fetch data");
      }
    },
    
    // Example action to insert data into database
    insertData: async (c, data) => {
      try {
        await pool.query(
          "INSERT INTO your_table (column1, column2) VALUES ($1, $2)", 
          [data.value1, data.value2]
        );
        
        c.state.lastQueryTime = Date.now();
        return { success: true };
      } catch (error) {
        console.error("Error inserting data:", error);
        throw new Error("Failed to insert data");
      }
    }
  }
});

export default databaseActor;
```

## With Drizzle ORM

Here's an example using Drizzle ORM for more type-safe database operations:

```typescript actor.ts
import { actor } from "actor-core";
import { drizzle } from "drizzle-orm/node-postgres";
import { pgTable, serial, text, timestamp } from "drizzle-orm/pg-core";
import { Pool } from "pg";

// Define your schema
const users = pgTable("users", {
  id: serial("id").primaryKey(),
  name: text("name").notNull(),
  email: text("email").notNull().unique(),
  createdAt: timestamp("created_at").defaultNow()
});

// Create a database connection
const pool = new Pool({
  connectionString: process.env.DATABASE_URL
});

// Initialize Drizzle with the pool
const db = drizzle(pool);

// Create the actor
const userActor = actor({
  state: {
    // Actor state (frequently accessed data can be cached here)
    userCache: {}
  },
  
  actions: {
    // Get a user by ID
    getUser: async (c, userId) => {
      // Check cache first
      if (c.state.userCache[userId]) {
        return c.state.userCache[userId];
      }
      
      // Query the database
      const result = await db.select().from(users).where(eq(users.id, userId));
      
      if (result.length === 0) {
        throw new Error(`User ${userId} not found`);
      }
      
      // Cache the result
      c.state.userCache[userId] = result[0];
      return result[0];
    },
    
    // Create a new user
    createUser: async (c, userData) => {
      const result = await db.insert(users).values({
        name: userData.name,
        email: userData.email
      }).returning();
      
      // Broadcast the new user event
      c.broadcast("userCreated", result[0]);
      
      return result[0];
    }
  }
});

export default userActor;
```


# Interacting with Actors
Source: https://actorcore.org/concepts/interacting-with-actors



This guide covers how to connect to and interact with actors from client applications.

## Setting Up the Client

The first step is to create a client that will connect to your actor service:

<CodeGroup>
  ```typescript TypeScript
  import { createClient } from "actor-core/client";
  import type { App } from "../src/index";

  // Create a client with the connection address and app type
  const client = createClient<App>(/* CONNECTION ADDRESS */);
  ```

  ```rust Rust
  use actor_core_client::{Client, TransportKind, EncodingKind};

  // Create a client with connection address and configuration
  let client = Client::new(
      "http://localhost:6420".to_string(),  // Connection address
      TransportKind::WebSocket,             // Transport (WebSocket or SSE)
      EncodingKind::Cbor,                   // Encoding (Json or Cbor)
  );
  ```
</CodeGroup>

<Tip>See the setup guide for your platform for details on how to get the connection address.</Tip>

## Finding & Connecting to Actors

ActorCore provides several methods to connect to actors:

### `get(tags, opts)` - Find or Create

The most common way to connect is with `get()`, which finds an existing actor matching the provided tags or creates a new one:

<CodeGroup>
  ```typescript TypeScript
  // Connect to a chat room for the "general" channel
  const room = await client.chatRoom.get({
    name: "chat_room",
    channel: "general"
  });

  // Now you can call methods on the actor
  await room.sendMessage("Alice", "Hello everyone!");
  ```

  ```rust Rust
  use actor_core_client::GetOptions;
  use serde_json::json;

  // Connect to a chat room for the "general" channel
  let tags = vec![
      ("name".to_string(), "chat_room".to_string()),
      ("channel".to_string(), "general".to_string()),
  ];

  let mut options = GetOptions {
      tags: Some(tags),
      ..Default::default()
  };

  let room = client.get("chatRoom", options)
      .await
      .expect("Failed to connect to chat room");

  // Now you can call methods on the actor
  room.action("sendMessage", vec![json!("Alice"), json!("Hello everyone!")])
      .await
      .expect("Failed to send message");
  ```
</CodeGroup>

### `create(opts)` - Explicitly Create New

When you specifically want to create a new actor instance:

<CodeGroup>
  ```typescript TypeScript
  // Create a new document actor
  const doc = await client.myDocument.create({
    create: {
      tags: {
        name: "my_document",
        docId: "123"
      }
    }
  });

  await doc.initializeDocument("My New Document");
  ```

  ```rust Rust
  use actor_core_client::{CreateOptions};
  use actor_core_client::client::CreateRequestMetadata;
  use serde_json::json;

  // Create a new document actor
  let tags = vec![
      ("name".to_string(), "my_document".to_string()),
      ("docId".to_string(), "123".to_string()),
  ];

  let create_options = CreateOptions {
      params: None,
      create: CreateRequestMetadata {
          tags,
          region: None,
      },
  };

  let doc = client.create("myDocument", create_options)
      .await
      .expect("Failed to create document");

  // Initialize the document
  doc.action("initializeDocument", vec![json!("My New Document")])
      .await
      .expect("Failed to initialize document");
  ```
</CodeGroup>

### `getWithId(id, opts)` - Connect by ID

Connect to an actor using its internal ID:

<CodeGroup>
  ```typescript TypeScript
  // Connect to a specific actor by its ID
  const myActorId = "55425f42-82f8-451f-82c1-6227c83c9372";
  const doc = await client.myDocument.getWithId(myActorId);

  await doc.updateContent("Updated content");
  ```

  ```rust Rust
  use actor_core_client::GetWithIdOptions;

  // Connect to a specific actor by its ID
  let my_actor_id = "55425f42-82f8-451f-82c1-6227c83c9372";
  let options = GetWithIdOptions {
      params: None,
  };
  let doc = client.get_with_id("myDocument", my_actor_id, options)
      .await
      .expect("Failed to connect to document");

  // Update content
  doc.action("updateContent", vec![json!("Updated content")])
      .await
      .expect("Failed to update document");
  ```
</CodeGroup>

<Note>
  It's usually better to use tags for discovery rather than directly using actor IDs.
</Note>

## Calling Actions

Once connected, calling actor actions are straightforward:

<CodeGroup>
  ```typescript TypeScript
  // Call an action
  const result = await mathUtils.multiplyByTwo(5);
  console.log(result); // 10

  // Call an action with multiple parameters
  await chatRoom.sendMessage("Alice", "Hello everyone!");

  // Call an action with an object parameter
  await gameRoom.updateSettings({
    maxPlayers: 10,
    timeLimit: 300,
    gameMode: "capture-the-flag"
  });
  ```

  ```rust Rust
  use serde_json::json;

  // Call an action
  let result = math_utils.action("multiplyByTwo", vec![json!(5)])
      .await
      .expect("Failed to call multiplyByTwo");
  println!("Result: {}", result.as_i64().unwrap()); // 10

  // Call an action with multiple parameters
  chat_room.action("sendMessage", vec![json!("Alice"), json!("Hello everyone!")])
      .await
      .expect("Failed to send message");

  // Call an action with an object parameter
  let settings = json!({
      "maxPlayers": 10,
      "timeLimit": 300,
      "gameMode": "capture-the-flag"
  });
  game_room.action("updateSettings", vec![settings])
      .await
      .expect("Failed to update settings");
  ```
</CodeGroup>

<Note>
  All actor action calls are asynchronous and require `await`, even if the actor's action is not async.
</Note>

## Listening for Events

Actors can send realtime updates to clients using events:

### `on(eventName, callback)` - Continuous Listening

To listen for events that will happen repeatedly:

<CodeGroup>
  ```typescript TypeScript
  // Listen for new chat messages
  chatRoom.on("newMessage", ({ sender, text, timestamp }) => {
    console.log(`${sender}: ${text}`);
    updateChatUI(sender, text, timestamp);
  });

  // Listen for game state updates
  gameRoom.on("stateUpdate", (gameState) => {
    updateGameUI(gameState);
  });
  ```

  ```rust Rust
  use std::sync::Arc;

  // Listen for new chat messages
  chat_room.on_event("newMessage", move |args| {
      let message = &args[0];
      let sender = message["sender"].as_str().unwrap();
      let text = message["text"].as_str().unwrap();
      println!("{}: {}", sender, text);
      // Update UI with message data
  }).await;

  // Listen for game state updates
  let game_ui = Arc::new(GameUI::new());
  let game_ui_clone = game_ui.clone();
  game_room.on_event("stateUpdate", move |args| {
      let game_state = &args[0];
      game_ui_clone.update(game_state);
  }).await;
  ```
</CodeGroup>

### `once(eventName, callback)` - One-time Listening

For events you only need to hear once:

<CodeGroup>
  ```typescript TypeScript
  // Listen for when a request is approved
  actor.once("requestApproved", () => {
    showApprovalNotification();
    unlockFeatures();
  });
  ```

  ```rust Rust
  // `once` is not implemented in Rust
  ```
</CodeGroup>

## Connection Options

### Authentication and Connection Parameters

Pass information with your connection using the `params` option:

<CodeGroup>
  ```typescript TypeScript
  const chatRoom = await client.chatRoom.get({ channel: "super-secret" }, {
    params: { 
      userId: "1234",
      authToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      displayName: "Alice"
    }
  });
  ```

  ```rust Rust
  use serde_json::json;
  use actor_core_client::GetOptions;

  let tags = vec![
      ("channel".to_string(), "super-secret".to_string()),
  ];

  let params = json!({
      "userId": "1234",
      "authToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "displayName": "Alice"
  });

  let options = GetOptions {
      tags: Some(tags),
      params: Some(params),
      no_create: None,
      create: None,
  };

  let chat_room = client.get("chatRoom", options)
      .await
      .expect("Failed to connect to chat room");
  ```
</CodeGroup>

The actor can access these parameters in the `onBeforeConnect` or `createConnState` hook:

```typescript
import { actor } from "actor-core";

const chatRoom = actor({
  state: { messages: [] },
  
  createConnState: (c, { params }) => {
    // Validate authentication token
    const { userId, authToken, displayName } = params;
    if (!validateToken(userId, authToken)) {
      throw new Error("Invalid authentication");
    }
    
    // Return connection state
    return { userId, displayName };
  },
  
  actions: {
    // ...
  }
});
```

Read more about [connection parameters](/concepts/connections).

### Additional Options

#### `opts.noCreate`

Connect only if an actor exists, without creating a new one:

```typescript
try {
  const doc = await client.document.get({ documentId: "doc-123" }, { noCreate: true });
  await doc.doSomething();
} catch (error) {
  console.log("Document doesn't exist");
}
```

## Client Options

<CodeGroup>
  ```typescript TypeScript
  // Example with all client options
  const client = createClient<App>(
    "https://actors.example.com",
    {
      // Data serialization format
      encoding: "cbor", // or "json"
      
      // Network transports in order of preference
      supportedTransports: ["websocket", "sse"]
    }
  );
  ```

  ```rust Rust
  use actor_core_client::{Client, TransportKind, EncodingKind};

  // Create client with specific options
  let client = Client::new(
      "https://actors.example.com".to_string(),
      TransportKind::WebSocket,  // or TransportKind::Sse
      EncodingKind::Cbor,        // or EncodingKind::Json
  );

  // Rust does not support accepting multiple transports
  ```
</CodeGroup>

### `encoding`

`"cbor" | "json"` (optional)

Specifies the data encoding format used for communication:

* `"cbor"` (default): Binary format that's more efficient for data transfer
* `"json"`: Text-based format with wider compatibility across environments

### `supportedTransports`

`("websocket" | "sse")[]` (optional)

Configures which network transport mechanisms the client will use to communicate with actors, sorted by priority:

* `"websocket"`: Real-time bidirectional communication, best for most applications
* `"sse"` (Server-Sent Events): Works in more restricted environments where WebSockets may be blocked

Default is `["websocket", "sse"]`, which automatically negotiates the best available option.

## Error Handling

ActorCore provides specific error types to help you handle different failure scenarios:

### Action Errors

When an action fails, it throws an error with details about the failure:

```typescript
try {
  await actor.someAction();
} catch (error) {
  console.error(`Action failed: ${error.code} - ${error.message}`);
  // Handle specific error codes
  if (error.code === "permission_denied") {
    // Handle permission errors
  }
}
```

These errors can be thrown from within the actor with `UserError`:

```typescript
import { actor, UserError } from "actor-core";

const documentActor = actor({
  state: { content: "" },
  
  actions: {
    editDocument: (c, userId, newContent) => {
      // Check if user has permission to edit
      if (!hasPermission(userId, "edit")) {
        throw new UserError("You don't have permission to edit this document", {
          code: "permission_denied",
          meta: { userId }
        });
      }
      
      c.state.content = newContent;
    }
  }
});
```

ActorCore doesn't expose internal errors to clients for security, helping to prevent the exposure of sensitive information or internal implementation details.

### Other Errors

Other common errors you might encounter:

* `InternalError`: Error from your actor that's not a subclass of `UserError`
* `ManagerError`: Issues when connecting to or communicating with the actor manager
* `NoSupportedTransport`: When the client and server have no compatible transport

## Disconnecting and Cleanup

The client connection is automatically cleaned up when it goes out of scope.

If you need to explicitly disconnect:

<CodeGroup>
  ```typescript TypeScript
  // Disconnect from the actor
  await actor.dispose();

  // Disconnect the entire client
  await client.dispose();
  ```

  ```rust Rust
  // Disconnect from the actor
  actor.disconnect().await;

  // The client will be cleaned up automatically when it goes out of scope
  // Or explicitly drop it with:
  drop(client);
  ```
</CodeGroup>

## Offline and Auto-Reconnection

Clients automatically attempt to reconnect (with [exponential backoff](https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/retry-backoff.html)) when disconnected. Actions made while disconnected are queued.

On reconnection, event subscriptions are reestablished & queued actions are executed.

This makes your applications resilient to temporary network failures without any extra code.

## Next Steps

<CardGroup>
  <Card title="State Management" href="/concepts/state">
    Learn how state works in actors
  </Card>

  <Card title="Events" href="/concepts/events">
    Learn more about actor events
  </Card>

  <Card title="Authentication" href="/concepts/authentication">
    Add security to your actors
  </Card>

  <Card title="Connections" href="/concepts/connections">
    Manage client connections
  </Card>
</CardGroup>


# Lifecycle
Source: https://actorcore.org/concepts/lifecycle



## Lifecycle Hooks

Actor lifecycle hooks are defined as functions in the actor configuration.

### `createState` and `state`

{/* [Documentation](https://jsr.io/@rivet-gg/actor/doc/~/Actor.prototype._onInitialize) */}

The `createState` function or `state` constant defines the initial state of the actor (see [state documentation](/concepts/state)). The `createState` function is called only once when the actor is first created.

### `createVars` and `vars`

The `createVars` function or `vars` constant defines ephemeral variables for the actor (see [state documentation](/concepts/state)). These variables are not persisted and are useful for storing runtime-only objects or temporary data.

The `createVars` function can also receive driver-specific context as its second parameter, allowing access to driver capabilities like Rivet KV or Cloudflare Durable Object storage.

```typescript
import { actor } from "actor-core";

// Using vars constant
const counter1 = actor({
  state: { count: 0 },
  vars: { lastAccessTime: 0 },
  actions: { /* ... */ }
});

// Using createVars function
const counter2 = actor({
  state: { count: 0 },
  createVars: () => {
    // Initialize with non-serializable objects
    return { 
      lastAccessTime: Date.now(),
      emitter: createNanoEvents() 
    };
  },
  actions: { /* ... */ }
});

// Access driver-specific context
const exampleActor = actor({
  state: { count: 0 },
  // Access driver context in createVars
  createVars: (c, rivet) => ({
    ctx: rivet.ctx,
  }),
  actions: {
    doSomething: (c) => {
      // Use driver-specific context
      console.log(`Region: ${c.vars.rivet.metadata.region.name}`);
    }
  }
});
```

### `onCreate`

The `onCreate` hook is called at the same time as `createState`, but unlike `createState`, it doesn't return any value. Use this hook for initialization logic that doesn't affect the initial state.

```typescript
import { actor } from "actor-core";

// Using state constant
const counter1 = actor({
  state: { count: 0 },
  actions: { /* ... */ }
});

// Using createState function
const counter2 = actor({
  createState: () => {
    // Initialize with a count of 0
    return { count: 0 };
  },
  actions: { /* ... */ }
});

// Using onCreate
const counter3 = actor({
  state: { count: 0 },
  
  // Run initialization logic (logging, external service setup, etc.)
  onCreate: (c) => {
    console.log("Counter actor initialized");
    // Can perform async operations or setup
    // No need to return anything
  },
  
  actions: { /* ... */ }
});
```

### `onStart`

{/* [Documentation](https://jsr.io/@rivet-gg/actor/doc/~/Actor.prototype._onStart) */}

This hook is called any time the actor is started (e.g. after restarting, upgrading code, or crashing).

This is called after the actor has been initialized but before any connections are accepted.

Use this hook to set up any resources or start any background tasks, such as `setInterval`.

```typescript
import { actor } from "actor-core";

const counter = actor({
  state: { count: 0 },
  
  onStart: (c) => {
    console.log('Actor started with count:', c.state.count);
    
    // Set up interval for automatic counting
    const intervalId = setInterval(() => {
      c.state.count++;
      console.log('Auto-increment:', c.state.count);
    }, 10000);
    
    // Store interval ID to clean up later if needed
    c.custom.intervalId = intervalId;
  },
  
  actions: { /* ... */ }
});
```

### `onStateChange`

{/* [Documentation](https://jsr.io/@rivet-gg/actor/doc/~/Actor.prototype._onStateChange) */}

Called whenever the actor's state changes. This is often used to broadcast state updates.

```typescript
import { actor } from "actor-core";

const counter = actor({
  state: { count: 0 },
  
  onStateChange: (c, newState) => {
    // Broadcast the new count to all connected clients
    c.broadcast('countUpdated', {
      count: newState.count
    });
  },
  
  actions: {
    increment: (c) => {
      c.state.count++;
      return c.state.count;
    }
  }
});
```

### `createConnState` and `connState`

{/* [Documentation](https://jsr.io/@rivet-gg/actor/doc/~/Actor.prototype._createConnState) */}

There are two ways to define the initial state for connections:

1. `connState`: Define a constant object that will be used as the initial state for all connections
2. `createConnState`: A function that dynamically creates initial connection state based on connection parameters

### `onBeforeConnect`

{/* [Documentation](https://jsr.io/@rivet-gg/actor/doc/~/Actor.prototype._onBeforeConnect) */}

The `onBeforeConnect` hook is called whenever a new client connects to the actor. Clients can pass parameters when connecting, accessible via `params`. This hook is used for connection validation and can throw errors to reject connections.

The `onBeforeConnect` hook does NOT return connection state - it's used solely for validation.

```typescript
import { actor } from "actor-core";

const chatRoom = actor({
  state: { messages: [] },
  
  // Method 1: Use a static default connection state
  connState: {
    role: "guest",
    joinTime: 0,
  },
  
  // Method 2: Dynamically create connection state
  createConnState: (c, { params }) => {
    return {
      userId: params.userId || "anonymous",
      role: params.role || "guest",
      joinTime: Date.now()
    };
  },
  
  // Validate connections before accepting them
  onBeforeConnect: (c, { params }) => {
    // Validate authentication
    const authToken = params.authToken;
    if (!authToken || !validateToken(authToken)) {
      throw new Error("Invalid authentication");
    }
    
    // Authentication is valid, connection will proceed
    // The actual connection state will come from connState or createConnState
  },
  
  actions: { /* ... */ }
});
```

Connections cannot interact with the actor until this method completes successfully. Throwing an error will abort the connection. This can be used for authentication - see [Authentication](/concepts/authentication) for details.

### `onConnect`

{/* [Documentation](https://jsr.io/@rivet-gg/actor/doc/~/Actor.prototype._onConnect) */}

Executed after the client has successfully connected.

```typescript
import { actor } from "actor-core";

const chatRoom = actor({
  state: { users: {}, messages: [] },
  
  onConnect: (c) => {
    // Add user to the room's user list using connection state
    const userId = c.conn.state.userId;
    c.state.users[userId] = {
      online: true,
      lastSeen: Date.now()
    };
    
    // Broadcast that a user joined
    c.broadcast("userJoined", { userId, timestamp: Date.now() });
    
    console.log(`User ${userId} connected`);
  },
  
  actions: { /* ... */ }
});
```

Messages will not be processed for this actor until this hook succeeds. Errors thrown from this hook will cause the client to disconnect.

### `onDisconnect`

{/* [Documentation](https://jsr.io/@rivet-gg/actor/doc/~/Actor.prototype._onDisconnect) */}

Called when a client disconnects from the actor. Use this to clean up any connection-specific resources.

```typescript
import { actor } from "actor-core";

const chatRoom = actor({
  state: { users: {}, messages: [] },
  
  onDisconnect: (c) => {
    // Update user status when they disconnect
    const userId = c.conn.state.userId;
    if (c.state.users[userId]) {
      c.state.users[userId].online = false;
      c.state.users[userId].lastSeen = Date.now();
    }
    
    // Broadcast that a user left
    c.broadcast("userLeft", { userId, timestamp: Date.now() });
    
    console.log(`User ${userId} disconnected`);
  },
  
  actions: { /* ... */ }
});
```

## Destroying Actors

Actors can be shut down gracefully with `c.shutdown()`. Clients will be gracefully disconnected.

```typescript
import { actor } from "actor-core";

const temporaryRoom = actor({
  state: { 
    createdAt: 0,
    expiresAfterMs: 3600000 // 1 hour
  },
  
  createState: () => ({
    createdAt: Date.now(),
    expiresAfterMs: 3600000 // 1 hour
  }),
  
  onStart: (c) => {
    // Check if room is expired
    const now = Date.now();
    const expiresAt = c.state.createdAt + c.state.expiresAfterMs;
    
    if (now > expiresAt) {
      console.log("Room expired, shutting down");
      c.shutdown();
    } else {
      // Set up expiration timer
      const timeUntilExpiry = expiresAt - now;
      setTimeout(() => {
        console.log("Room lifetime reached, shutting down");
        c.shutdown();
      }, timeUntilExpiry);
    }
  },
  
  actions: {
    closeRoom: (c) => {
      // Notify all clients
      c.broadcast("roomClosed", { reason: "Admin closed the room" });
      
      // Shutdown the actor
      c.shutdown();
    }
  }
});
```

This action is permanent and cannot be reverted.

## Using `ActorContext` Type Externally

When extracting logic from lifecycle hooks or actions into external functions, you'll often need to define the type of the context parameter. ActorCore provides helper types that make it easy to extract and pass these context types to external functions.

```typescript
import { actor, ActorContextOf } from "actor-core";

const myActor = actor({
  state: { count: 0 },
  
  // Use external function in lifecycle hook
  onStart: (c) => logActorStarted(c)
});

// Simple external function with typed context
function logActorStarted(c: ActorContextOf<typeof myActor>) {
  console.log(`Actor started with count: ${c.state.count}`);
}
```

See [Helper Types](/concepts/types) for more details on using `ActorContextOf`.

## Full Example

```typescript
import { actor } from "actor-core";

const counter = actor({
  // Initialize state
  createState: () => ({
    count: 0
  }),
  
  // Initialize actor (run setup that doesn't affect initial state)
  onCreate: (c) => {
    console.log('Counter actor initialized');
    // Set up external resources, etc.
  },
  
  // Define default connection state
  connState: {
    role: "guest"
  },
  
  // Dynamically create connection state based on params
  createConnState: (c, { params }) => {
    // Get auth info from validation
    const authToken = params.authToken;
    const authInfo = validateAuthToken(authToken);
    
    return {
      userId: authInfo?.userId || "anonymous",
      role: authInfo?.role || "guest"
    };
  },
  
  // Lifecycle hooks
  onStart: (c) => {
    console.log('Counter started with count:', c.state.count);
  },
  
  onStateChange: (c, newState) => {
    c.broadcast('countUpdated', { count: newState.count });
  },
  
  onBeforeConnect: (c, { params }) => {
    // Validate auth token
    const authToken = params.authToken;
    if (!authToken) {
      throw new Error('Missing auth token');
    }
    
    // Validate with your API and determine the user
    const authInfo = validateAuthToken(authToken);
    if (!authInfo) {
      throw new Error('Invalid auth token');
    }
    
    // If validation succeeds, connection proceeds
    // Connection state will be set by createConnState
  },
  
  onConnect: (c) => {
    console.log(`User ${c.conn.state.userId} connected`);
  },
  
  onDisconnect: (c) => {
    console.log(`User ${c.conn.state.userId} disconnected`);
  },
  
  // Define actions
  actions: {
    increment: (c) => {
      c.state.count++;
      return c.state.count;
    },
    
    reset: (c) => {
      // Check if user has admin role
      if (c.conns.state.role !== "admin") {
        throw new Error("Unauthorized: requires admin role");
      }
      
      c.state.count = 0;
      return c.state.count;
    }
  }
});

export default counter;
```


# Logging
Source: https://actorcore.org/concepts/logging



Actors provide a built-in way to log complex data to the console.

When dealing with lots of data, `console.log` often doesn't cut it. Using the context's log object (`c.log`) allows you to log complex data using structured logging.

<Note>Using the actor logging API is completely optional.</Note>

## Log levels

There are 5 log levels:

| Level    | Call                                | Description                                                      |
| -------- | ----------------------------------- | ---------------------------------------------------------------- |
| Critical | `c.log.critical(message, ...args);` | Severe errors that prevent core functionality                    |
| Error    | `c.log.error(message, ...args);`    | Errors that affect functionality but allow continued operation   |
| Warning  | `c.log.warn(message, ...args);`     | Potentially harmful situations that should be addressed          |
| Info     | `c.log.info(message, ...args);`     | General information about significant events & state changes     |
| Debug    | `c.log.debug(message, ...args);`    | Detailed debugging information, usually used only in development |

## Structured logging

The built-in logging API (using `c.log`) provides structured logging to let you log key-value
pairs instead of raw strings. Structures logs are readable by both machines &
humans to make them easier to parse & search.

Passing an object to a log will print as structured data. For example:

```typescript
c.log.info('increment', { connection: c.conn.id, count });
// Prints: level=INFO msg=increment connection=123 count=456
```

The first parameter in each log method is the message. The rest of the arguments are used for structured logging.

## `c.log` vs `console.log` logging

`c.log` makes it easier to manage complex logs, while `console.log` can
become unmaintainable at scale.

Consider this example:

<CodeGroup>
  ```typescript structured_logging.ts
  import { actor } from "actor-core";

  const counter = actor({
    state: { count: 0 },
    
    actions: {
      increment: (c, count) => {
        // Prints: level=INFO msg=increment connection=123 count=456
        c.log.info('increment', { connection: c.conn.id, count });

        c.state.count += count;
        return c.state.count;
      }
    }
  });
  ```

  ```typescript unstructured_logging.ts
  import { actor } from "actor-core";

  const counter = actor({
    state: { count: 0 },
    
    actions: {
      increment: (c, count) => {
        // Prints: Increment for connection 123 with count 456
        console.log(`Increment for connection ${c.conn.id} with count ${count}`);

        c.state.count += count;
        return c.state.count;
      }
    }
  });
  ```
</CodeGroup>

If you need to search through a lot of logs, it's easier to read the structured logs. To find increments for a single connection, you can search `connection=123`.

Additionally, structured logs can be parsed and queried at scale using tools like Elasticsearch, Loki, or Datadog. For example, you can parse the log `level=INFO msg=increment connection=123 count=456` in to the JSON object `{"level":"INFO","msg":"increment","connection":123,"count":456}` and then query it as you would any other structured data.

## Usage in lifecycle hooks

The logger is available in all lifecycle hooks:

```typescript
import { actor } from "actor-core";

const loggingExample = actor({
  state: { events: [] },
  
  onStart: (c) => {
    c.log.info('actor_started', { timestamp: Date.now() });
  },
  
  onBeforeConnect: (c, { params }) => {
    c.log.debug('connection_attempt', { 
      ip: params.ip,
      timestamp: Date.now() 
    });
    
    return { authorized: true };
  },
  
  onConnect: (c) => {
    c.log.info('connection_established', { 
      connectionId: c.conn.id,
      timestamp: Date.now() 
    });
    
    c.state.events.push({
      type: 'connect',
      connectionId: c.conn.id,
      timestamp: Date.now()
    });
  },
  
  onDisconnect: (c) => {
    c.log.info('connection_closed', { 
      connectionId: c.conn.id,
      timestamp: Date.now() 
    });
    
    c.state.events.push({
      type: 'disconnect',
      connectionId: c.conn.id,
      timestamp: Date.now()
    });
  },
  
  actions: {
    // Actor actions...
  }
});
```


# Metadata
Source: https://actorcore.org/concepts/metadata



Metadata provides information about the currently running actor.

## Region

Region can be accessed from the context object via `c.region`.

<Warning>`c.region` is only supported on Rivet at the moment.</Warning>

## Tags

Tags can be accessed from the context object via `c.tags`.

For example:

<CodeGroup>
  ```typescript chat_room.ts
  import { actor } from "actor-core";

  const chatRoom = actor({
    state: {
      messages: []
    },
    
    actions: {
      // Method used to get the channel ID
      getChannelId: (c) => {
        return c.tags['channel'];
      },
      
      addMessage: (c, message) => {
        // Use the channel for logging or filtering
        const channel = c.tags['channel'] || 'default';
        console.log(`Adding message to channel: ${channel}`);
        
        c.state.messages.push({
          channel,
          message,
          timestamp: Date.now()
        });
        
        c.broadcast('newMessage', { channel, message });
      }
    }
  });

  export default chatRoom;
  ```

  ```typescript client.ts
  import { createClient } from "actor-core/client";
  import type { App } from "./src/index";

  const client = createClient<App>("http://localhost:6420");

  // Connect to a specific channel
  const randomChannel = await client.chatRoom.get({ channel: "random" });

  // Check the channel ID
  const channelId = await randomChannel.getChannelId();
  console.log("Connected to channel:", channelId); // "random"

  // Or connect with multiple parameters
  const teamChannel = await client.chatRoom.get({
    channel: "team-chat",
    teamId: "engineering"
  });
  ```
</CodeGroup>

## Actor Name

You can access the actor name with:

```typescript
const actorName = c.name;
```

This is useful when you need to know which actor type is running, especially if you have generic utility functions that are shared between different actor implementations.


# Introduction
Source: https://actorcore.org/concepts/overview



Actors combine compute and storage into unified entities for simplified architecture. Actors seamlessly integrate with your existing infrastructure or can serve as a complete standalone solution.

## Quickstart

Run this to get started:

<CodeGroup>
  ```sh npx
  npx create-actor@latest
  ```

  ```sh npm
  npm create actor@latest
  ```

  ```sh pnpm
  pnpm create actor@latest
  ```

  ```sh yarn
  yarn create actor@latest
  ```

  ```sh bun
  bun create actor@latest
  ```
</CodeGroup>

## Code Example

Here's a complete chat room actor that maintains state and handles messages. We'll explore each component in depth throughout this document:

```typescript chat_room.ts
import { actor } from "actor-core";

// Define a chat room actor
const chatRoom = actor({
  // Initialize state when the actor is first created
  createState: () => ({
    messages: []
  }),

  // Define actions clients can call
  actions: {
    // Action to send a message
    sendMessage: (c, sender, text) => {
      // Update state
      c.state.messages.push({ sender, text });
      
      // Broadcast to all connected clients
      c.broadcast("newMessage", { sender, text });
    },
    
    // Action to get chat history
    getHistory: (c) => {
      return c.state.messages;
    }
  }
});

export default chatRoom;
```

## Using the App

To start using your actor, create an app and serve it:

```typescript app.ts
import { setup, serve } from "actor-core";
import chatRoom from "./chat_room";

// Create the application
const app = setup({
  actors: { chatRoom }
});

// Start serving on default port
serve(app);

// Export the app type for client usage
export type App = typeof app;
```

## Key Actor Components

### State

Actors maintain state that's stored in memory and automatically persisted. State is defined either as a constant or via a `createState` function:

```typescript
import { actor } from "actor-core";

// Method 1: State constant
const counter1 = actor({
  state: { count: 0 },
  actions: {
    // ...
  }
});

// Method 2: CreateState function
const counter2 = actor({
  createState: () => ({ count: 0 }),
  actions: {
    // ...
  }
});
```

Update state by modifying `c.state` in your actions:

```typescript
import { actor } from "actor-core";

const counter = actor({
  state: { count: 0 },
  actions: {
    // Example of state update in an action
    increment: (c) => {
      c.state.count += 1;
      return c.state.count;
    }
  }
});
```

These changes are durable and are automatically persisted across updates, restarts, and crashes.

Learn more about [state management](/concepts/state).

### Actions

Actions are functions defined in your actor configuration that clients & other actors can call:

```typescript
import { actor } from "actor-core";

const mathUtils = actor({
  state: {},
  actions: {
    multiplyByTwo: (c, x) => {
      return x * 2;
    }
  }
});
```

Each action receives a context object (commonly named `c`) as its first parameter, which provides access to state, connections, and other utilities.

Learn more about [actions](/concepts/actions).

### Events

Actors can broadcast events to connected clients:

```typescript
import { actor } from "actor-core";

const inventory = actor({
  createState: () => ({ 
    items: [] 
  }),
  
  actions: {
    addItem: (c, item) => {
      // Add to state
      c.state.items.push(item);
      
      // Notify all clients about the new item
      c.broadcast("itemAdded", { item });
    }
  }
});
```

You can also send events to specific clients:

```typescript
import { actor } from "actor-core";

const messageService = actor({
  state: {},
  actions: {
    sendPrivateMessage: (c, userId, text) => {
      // Send to a specific connection
      const conn = c.conns.find(conn => conn.params.userId === userId);
      if (conn) {
        conn.send("privateMessage", { text });
      }
    }
  }
});
```

Learn more about [events](/concepts/events).

## Actor Tags

Tags are key-value pairs attached to actors that serve two purposes:

1. **Actor Discovery**: Find specific actors using `client.get(tags)`
2. **Organization**: Group related actors for management purposes

For example, you can query chat rooms by tag like:

```typescript client.ts
await client.chatRoom.get({ channel: "random" });
```

### Common Tag Patterns

```typescript
import { createClient } from "actor-core/client";
import type { App } from "./src/index";

const client = createClient<App>("http://localhost:6420");

// Game room with ID parameter
const gameRoom = await client.gameRoom.get({ roomId: "ABC123" });

// User profile with ID
const userProfile = await client.userProfile.get({ profileId: "1234" });

// Document with multiple parameters
const document = await client.document.get({
  workspaceId: "team-alpha",
  documentId: "budget-2024"
});
```

## Actor Lifecycle

Actors are created automatically when needed and persist until explicitly shutdown.

To shut down an actor, use `c.shutdown()` from within an action:

```typescript
import { actor } from "actor-core";

const chatRoom = actor({
  createState: () => ({
    messages: []
  }),
  actions: {
    closeRoom: (c) => {
      // Do any cleanup needed
      c.broadcast("roomClosed");
      
      // Shutdown the actor
      c.shutdown();
    }
  }
});
```

Learn more about the [actor lifecycle](/concepts/lifecycle).

## Next Steps

<CardGroup>
  <Card title="Interacting with Actors" href="/concepts/interacting-with-actors">
    Learn how to connect to actors from clients
  </Card>

  <Card title="State" href="/concepts/state">
    Deep dive into actor state management
  </Card>

  <Card title="Actions" href="/concepts/actions">
    Learn more about actor actions
  </Card>

  <Card title="Events" href="/concepts/events">
    Learn more about realtime events
  </Card>
</CardGroup>


# Scaling & Concurrency
Source: https://actorcore.org/concepts/scaling



This document covers how actors are able to scale better than traditional applications & provides tips on architecting your actors.

## How actors scale

Actors scale by design through these key properties:

| Property                                | Description                                                                                                                                                                                                                                                                                     |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Independent State**                   | Each actor manages its own private data separately from other actors, so they never conflict with each other when running at the same time (i.e. using locking mechanisms).                                                                                                                     |
| **Action- & Event-Based Communication** | Actors communicate through asynchronous [actions](/concepts/actions) or [events](/concepts/events), making it easy to distribute them across different machines.                                                                                                                                |
| **Location Transparency**               | Unlike traditional servers, actors don't need to know which machine other actors are running on in order to communicate with each other. They can run on the same machine, across a network, and across the world. Actors handle the network routing for you under the hood.                    |
| **Horizontal Scaling**                  | Actors distribute workload by splitting responsibilities into small, focused units. Since each actor handles a limited scope (like a single user, document, or chat room), the system automatically spreads load across many independent actors rather than concentrating it in a single place. |

## Tips for architecting actors for scale

Here are key principles for architecting your actor system:

**Single Responsibility**

* Each actor should represent one specific entity or concept from your application (e.g., `User`, `Document`, `ChatRoom`).
* This makes your system scale better, since actors have small scopes and do not conflict with each other.

**State Management**

* Each actor owns and manages only its own state
* Use [actions](/concepts/actions) to request data from other actors
* Keep state minimal and relevant to the actor's core responsibility

**Granularity Guidelines**

* Too coarse: Actors handling too many responsibilities become bottlenecks
* Too fine: Excessive actors create unnecessary communication overhead
* Aim for actors that can operate independently with minimal cross-actor communication

### Examples

**Good actor boundaries**

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

**Poor actor boundaries**

* `Application`: Too broad, handles everything
* `DocumentWordCount`: Too granular, should be part of DocumentActor


# Schedule
Source: https://actorcore.org/concepts/schedule



Scheduling is used to trigger events in the future. The actor scheduler is like `setTimeout`, except the timeout will persist even if the actor restarts, upgrades, or crashes.

## Use Cases

Scheduling is helpful for long-running timeouts like month-long billing periods or account trials.

## Scheduling

### `c.schedule.after(duration, fn, ...args)`

Schedules a function to be executed after a specified duration. This function persists across actor restarts, upgrades, or crashes.

Parameters:

* `duration` (number): The delay in milliseconds.
* `fn` (string): The name of the action to be executed.
* `...args` (unknown\[]): Additional arguments to pass to the function.

### `c.schedule.at(timestamp, fn, ...args)`

Schedules a function to be executed at a specific timestamp. This function persists across actor restarts, upgrades, or crashes.

Parameters:

* `timestamp` (number): The exact time in milliseconds since the Unix epoch when the function should be executed.
* `fn` (string): The name of the action to be executed.
* `...args` (unknown\[]): Additional arguments to pass to the function.

## Scheduling Private Actions

Currently, scheduling can only trigger public actions. If the scheduled action is private, it needs to be secured with something like a token.

## Full Example

```typescript
import { actor } from "actor-core";

const reminderService = actor({
  state: {
    reminders: {}
  },
  
  actions: {
    setReminder: (c, userId, message, delayMs) => {
      const reminderId = crypto.randomUUID();
      
      // Store the reminder in state
      c.state.reminders[reminderId] = {
        userId,
        message,
        scheduledFor: Date.now() + delayMs
      };
      
      // Schedule the sendReminder action to run after the delay
      c.after(delayMs, "sendReminder", reminderId);
      
      return { reminderId };
    },
    
    sendReminder: (c, reminderId) => {
      const reminder = c.state.reminders[reminderId];
      if (!reminder) return;
      
      // Find the user's connection if they're online
      const userConn = c.conns.find(
        conn => conn.state.userId === reminder.userId
      );
      
      if (userConn) {
        // Send the reminder to the user
        userConn.send("reminder", {
          message: reminder.message,
          scheduledAt: reminder.scheduledFor
        });
      } else {
        // If user is offline, store reminder for later delivery
        // ...
      }
      
      // Clean up the processed reminder
      delete c.state.reminders[reminderId];
    }
  }
});
```


# State
Source: https://actorcore.org/concepts/state



Actor state provides the best of both worlds: it's stored in-memory and persisted automatically. This lets you work with the data without added latency while still being able to survive crashes & upgrades.

<Tip>
  **Using External SQL Databases**

  Actors can also be used with external SQL databases. This can be useful to integrate actors with existing
  applications or for storing relational data. Read more [here](/concepts/external-sql).
</Tip>

## Initializing State

There are two ways to define an actor's initial state:

**Method 1: Static Initial State**

```typescript
import { actor } from "actor-core";

// Simple state with a constant
const counter = actor({
  // Define state as a constant
  state: { count: 0 },
  
  actions: {
    // ...
  }
});
```

**Method 2: Dynamic Initial State**

```typescript
import { actor } from "actor-core";

// State with initialization logic
const counter = actor({
  // Define state using a creation function
  createState: () => {
    return { count: 0 };
  },
  
  actions: {
    // ...
  }
});
```

The `createState` function is called once when the actor is first created. See [Lifecycle](/concepts/lifecycle) for more details.

## Modifying State

To update state, modify the `state` property on the context object (`c.state`) in your actions:

```typescript
import { actor } from "actor-core";

const counter = actor({
  state: { count: 0 },
  
  actions: {
    // Define action to update state
    increment: (c) => {
      // Update state, this will automatically be persisted
      c.state.count += 1;
      return c.state.count;
    },
    
    add: (c, value) => {
      c.state.count += value;
      return c.state.count;
    }
  }
});
```

<Note>
  Only state stored in the `state` object will be persisted. Any other variables or properties outside of this are not persisted.
</Note>

## State Saves

Actors automatically handle persisting state transparently. This happens at the end of every action if the state has changed.

In the rare occasion you need to force a state change mid-action, you can use `c.saveState()`. This should only be used if your action makes an important state change that needs to be persisted before the action completes.

```typescript
import { actor } from "actor-core";

const criticalProcess = actor({
  state: { 
    steps: [],
    currentStep: 0
  },
  
  actions: {
    processStep: async (c) => {
      // Update to current step
      c.state.currentStep += 1;
      c.state.steps.push(`Started step ${c.state.currentStep}`);
      
      // Force save state before the async operation
      c.saveState();
      
      // Long-running operation that might fail
      await someRiskyOperation();
      
      // Update state again
      c.state.steps.push(`Completed step ${c.state.currentStep}`);
      
      return c.state.currentStep;
    }
  }
});
```

## State Isolation

Each actor's state is completely isolated, meaning it cannot be accessed directly by other actors or clients. This allows actors to maintain a high level of security and data integrity, ensuring that state changes are controlled and predictable.

To interact with an actor's state, you must use [Actions](/concepts/actions). Actions provide a controlled way to read from and write to the state.

## Sharing State Between Actors

If you need a shared state between multiple actors, you have two options:

1. Create an actor that holds the shared state that other actors can make action calls to
2. Use an external database, see [External SQL Databases](/concepts/external-sql)

## Ephemeral Variables

In addition to persisted state, ActorCore provides a way to store ephemeral data that is not saved to permanent storage using `vars`. This is useful for temporary data that only needs to exist while the actor is running or data that cannot be serialized.

`vars` is designed to complement `state`, not replace it. Most actors should use both: `state` for critical business data and `vars` for ephemeral or non-serializable data.

### Initializing Variables

There are two ways to define an actor's initial vars:

**Method 1: Static Initial Variables**

```typescript
import { actor } from "actor-core";

// Define vars as a constant
const counter = actor({
  state: { count: 0 },
  
  // Define ephemeral variables
  vars: { 
    lastAccessTime: 0,
    emitter: createNanoEvents()
  },
  
  actions: {
    // ...
  }
});
```

<Warning>
  When using static `vars`, all values must be compatible with `structuredClone()`. If you need to use non-serializable objects, use `createVars` instead, which allows you to create these objects on the fly.
</Warning>

**Method 2: Dynamic Initial Variables**

```typescript
import { actor } from "actor-core";

// Define vars with initialization logic
const counter = actor({
  state: { count: 0 },
  
  // Define vars using a creation function
  createVars: () => {
    return { 
      lastAccessTime: Date.now(),
      emitter: createNanoEvents()
    };
  },
  
  actions: {
    // ...
  }
});
```

### Using Variables

Vars can be accessed and modified through the context object with `c.vars`:

```typescript
import { actor } from "actor-core";
import { createNanoEvents } from "nanoevents";

const counter = actor({
  // Persistent state - saved to storage
  state: { count: 0 },
  
  // Create ephemeral objects that won't be serialized
  createVars: () => {
    // Create an event emitter (can't be serialized)
    const emitter = createNanoEvents();
    
    // Set up event listener directly in createVars
    emitter.on('count-changed', (newCount) => {
      console.log(`Count changed to: ${newCount}`);
    });
    
    return { emitter };
  },
  
  actions: {
    increment: (c) => {
      // Update persistent state
      c.state.count += 1;
      
      // Use non-serializable emitter
      c.vars.emitter.emit('count-changed', c.state.count);
      
      return c.state.count;
    }
  }
});
```

### When to Use `vars` vs `state`

In practice, most actors will use both: `state` for critical business data and `vars` for ephemeral, non-serializable, or performance-sensitive data.

Use `vars` when:

* You need to store temporary data that doesn't need to survive restarts
* You need to maintain runtime-only references that can't be serialized (database connections, event emitters, class instances, etc.)

Use `state` when:

* The data must be preserved across actor sleeps, restarts, updates, or crashes
* The information is essential to the actor's core functionality and business logic

## Limitations

State is constrained to the available memory.

Only JSON-serializable types can be stored in state. In serverless runtimes that support it (Rivet, Cloudflare Workers), state is persisted under the hood in a compact, binary format. This is because JavaScript classes cannot be serialized & deserialized.


# Testing
Source: https://actorcore.org/concepts/testing



ActorCore provides a straightforward testing framework to build reliable and maintainable applications. This guide covers how to write effective tests for your actor-based services.

## Setup

To set up testing with ActorCore:

```bash
# Install Vitest
npm install -D vitest

# Run tests
npm test
```

## Basic Testing Setup

ActorCore includes a test helper called `setupTest` that configures a test environment with in-memory drivers for your actors. This allows for fast, isolated tests without external dependencies.

<CodeGroup>
  ```ts tests/my-actor.test.ts
  import { test, expect } from "vitest";
  import { setupTest } from "actor-core/test";
  import { app } from "../src/index";

  test("my actor test", async (test) => {
    const { client } = await setupTest(test, app);
    
    // Now you can interact with your actor through the client
    const myActor = await client.myActor.get();
    
    // Test your actor's functionality
    await myActor.someAction();
    
    // Make assertions
    const result = await myActor.getState();
    expect(result).toEqual("updated");
  });
  ```

  ```ts src/index.ts
  import { actor, setup } from "actor-core";

  const myActor = actor({
    state: { value: "initial" },
    actions: {
      someAction: (c) => {
        c.state.value = "updated";
        return c.state.value;
      },
      getState: (c) => {
        return c.state.value;
      }
    }
  });

  export const app = setup({
    actors: { myActor }
  });

  export type App = typeof app;
  ```
</CodeGroup>

## Testing Actor State

The test framework uses in-memory drivers that persist state within each test, allowing you to verify that your actor correctly maintains state between operations.

<CodeGroup>
  ```ts tests/counter.test.ts
  import { test, expect } from "vitest";
  import { setupTest } from "actor-core/test";
  import { app } from "../src/index";

  test("actor should persist state", async (test) => {
    const { client } = await setupTest(test, app);
    const counter = await client.counter.get();
    
    // Initial state
    expect(await counter.getCount()).toBe(0);
    
    // Modify state
    await counter.increment();
    
    // Verify state was updated
    expect(await counter.getCount()).toBe(1);
  });
  ```

  ```ts src/index.ts
  import { setup } from "actor-core";

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

  export const app = setup({
    actors: { counter }
  });

  export type App = typeof app;
  ```
</CodeGroup>

## Testing Events

For actors that emit events, you can verify events are correctly triggered by subscribing to them:

<CodeGroup>
  ```ts tests/chat-room.test.ts
  import { test, expect, vi } from "vitest";
  import { setupTest } from "actor-core/test";
  import { app } from "../src/index";

  test("actor should emit events", async (test) => {
    const { client } = await setupTest(test, app);
    const chatRoom = await client.chatRoom.get();
    
    // Set up event handler with a mock function
    const mockHandler = vi.fn();
    chatRoom.on("newMessage", mockHandler);
    
    // Trigger the event
    await chatRoom.sendMessage("testUser", "Hello world");
    
    // Wait for the event to be emitted
    await vi.waitFor(() => {
      expect(mockHandler).toHaveBeenCalledWith("testUser", "Hello world");
    });
  });
  ```

  ```ts src/index.ts
  import { actor, setup } from "actor-core";

  export const chatRoom = actor({
    state: { 
      messages: []
    },
    actions: {
      sendMessage: (c, username: string, message: string) => {
        c.state.messages.push({ username, message });
        c.broadcast("newMessage", username, message);
      },
      getHistory: (c) => {
        return c.state.messages;
      },
    },
  });

  // Create and export the app
  export const app = setup({
    actors: { chatRoom }
  });

  // Export type for client type checking
  export type App = typeof app;
  ```
</CodeGroup>

## Testing Schedules

ActorCore's schedule functionality can be tested using Vitest's time manipulation utilities:

<CodeGroup>
  ```ts tests/scheduler.test.ts
  import { test, expect, vi } from "vitest";
  import { setupTest } from "actor-core/test";
  import { app } from "../src/index";

  test("scheduled tasks should execute", async (test) => {
    // setupTest automatically configures vi.useFakeTimers()
    const { client } = await setupTest(test, app);
    const scheduler = await client.scheduler.get();
    
    // Set up a scheduled task
    await scheduler.scheduleTask("reminder", 60000); // 1 minute in the future
    
    // Fast-forward time by 1 minute
    await vi.advanceTimersByTimeAsync(60000);
    
    // Verify the scheduled task executed
    expect(await scheduler.getCompletedTasks()).toContain("reminder");
  });
  ```

  ```ts src/index.ts
  import { actor, setup } from "actor-core";

  const scheduler = actor({
    state: { 
      tasks: [],
      completedTasks: []
    },
    actions: {
      scheduleTask: (c, taskName: string, delayMs: number) => {
        c.state.tasks.push(taskName);
        // Schedule "completeTask" to run after the specified delay
        c.schedule.after(delayMs, "completeTask", taskName);
        return { success: true };
      },
      completeTask: (c, taskName: string) => {
        // This action will be called by the scheduler when the time comes
        c.state.completedTasks.push(taskName);
        return { completed: taskName };
      },
      getCompletedTasks: (c) => {
        return c.state.completedTasks;
      }
    }
  });

  export const app = setup({
    actors: { scheduler }
  });

  export type App = typeof app;
  ```
</CodeGroup>

The `setupTest` function automatically calls `vi.useFakeTimers()`, allowing you to control time in your tests with functions like `vi.advanceTimersByTimeAsync()`. This makes it possible to test scheduled operations without waiting for real time to pass.

## Best Practices

1. **Isolate tests**: Each test should run independently, avoiding shared state.
2. **Test edge cases**: Verify how your actor handles invalid inputs, concurrent operations, and error conditions.
3. **Mock time**: Use Vitest's timer mocks for testing scheduled operations.
4. **Use realistic data**: Test with data that resembles production scenarios.

ActorCore's testing framework automatically handles server setup and teardown, so you can focus on writing effective tests for your business logic.


# Topologies
Source: https://actorcore.org/concepts/topology



ActorCore supports three topologies that define how actors are distributed and scale.

<Warning>
  Each platform configures a default topology appropriate for that environment. In most cases, you can rely on these defaults unless you have specific distribution needs.
</Warning>

## Configuration

```typescript
const config = {
  topology: "standalone" // or "partition" or "coordinate"
};
```

## Types of Topologies

### Standalone

* **How it works**: Runs all actors in a single process
* **When to use**: Development, testing, simple apps with low traffic
* **Limitations**: No horizontal scaling, single point of failure
* **Default on**: Node.js, Bun

### Partition

* **How it works**: Each actor has its own isolated process. Clients connect directly to the actor for optimal performance.
* **When to use**: Production environments needing horizontal scaling
* **Limitations**: Minimal - balanced performance and availability for most use cases
* **Default on**: Rivet, Cloudflare Workers

### Coordinate

* **How it works**: Creates a peer-to-peer network between multiple servers with leader election with multiple actors running on each server. Clients connect to any server and data is transmitted to the leader over a pubsub server.
* **When to use**: High-availability scenarios needing redundancy and failover
* **Limitations**: Added complexity, performance overhead, requires external data source
* **Default on**: *None*

## Choosing a Topology

In most cases, use your platform's default:

1. **Standalone**: Simple, great for development
2. **Partition**: Best scaling & cost for production
3. **Coordinate**: Good for specialized deployment scenarios


# Helper Types
Source: https://actorcore.org/concepts/types



ActorCore provides several TypeScript helper types to make it easier to work with actors in a type-safe way.

## `Context` Types

When working with actors, you often need to access the context object. ActorCore provides helper types to extract the context types from actor definitions.

### `ActorContextOf<ActorDefinition>`

Extracts the full actor context type from an actor definition. This is the type of the context object (`c`) available in lifecycle hooks such as `onCreate`, `onStart`, etc.

```typescript
import { actor, ActorContextOf } from "actor-core";

const chatRoom = actor({
  state: { messages: [] },
  actions: {
    sendMessage: (c, message) => {
      // ...
    }
  }
});

// Extract the chat room context type
type ChatRoomContext = ActorContextOf<typeof chatRoom>;

// Now you can use this type elsewhere
function processChatRoomContext(context: ChatRoomContext) {
  // Access context properties with full type safety
  console.log(context.state.messages);
  context.broadcast("newEvent", { type: "system" });
}
```

### `ActionContextOf<ActorDefinition>`

Extracts the action context type from an actor definition. This is the type of the context object (`c`) available in action handlers.

```typescript
import { actor, ActionContextOf } from "actor-core";

const counter = actor({
  state: { count: 0 },
  actions: {
    increment: (c) => {
      c.state.count++;
      return c.state.count;
    }
  }
});

// Extract the action context type
type CounterActionContext = ActionContextOf<typeof counter>;

// Use in other functions that need to work with the action context
function processCounterAction(context: CounterActionContext) {
  // Access context with full type safety
  context.state.count++;
}
```


# Building Drivers
Source: https://actorcore.org/drivers/build



Each driver implements common interfaces defined by ActorCore, including:

* **ActorDriver**: Manages actor state, lifecycle, and persistence
* **ManagerDriver**: Handles actor discovery, routing, and scaling
* **CoordinateDriver**: Facilitates peer-to-peer communication between actor instances (only relevant for the coordinated topology)

## Source Code Locations

Get started by looking at source code for the driver interfaces and existing drivers:

* **Driver Interfaces**
  * **ActorDriver**\* `packages/actor-core/src/actor/runtime/driver.ts`
  * **ManagerDriver**\* `packages/actor-core/src/actor/runtime/driver.ts`
  * **CoordinateDriver**: `packages/actor-core/src/topologies/coordinate/driver.ts`
* **Driver Implementations**
  * **Memory driver**: `packages/drivers/memory/`
  * **Redis driver**: `packages/drivers/redis/`
  * More drivers are available in `packages/drivers/`


# Cloudflare Workers (Durable Objects)
Source: https://actorcore.org/drivers/cloudflare-workers



The Cloudflare Workers Driver is an implementation that uses Cloudflare's Durable Objects for actor state persistence and coordination. It leverages Cloudflare's global network for low-latency, distributed actor systems that can scale automatically.

<Info>
  You rarely need to manually configure drivers. The platform package you're using will configure the appropriate drivers for you. See the documentation for your platform for details.
</Info>

## Compatibility

| Platforms                                                   | Topologies                                                     |
| ----------------------------------------------------------- | -------------------------------------------------------------- |
| <Icon icon="xmark" iconType="solid" color="gray" /> Node.js | <Icon icon="xmark" iconType="solid" color="gray" /> Standalone |
| <Icon icon="xmark" iconType="solid" color="gray" /> Bun     | <Icon icon="xmark" iconType="solid" color="gray" /> Coordinate |
| <Icon icon="check" iconType="solid" /> Cloudflare Workers   | <Icon icon="check" iconType="solid" /> Partition               |
| <Icon icon="xmark" iconType="solid" color="gray" /> Rivet   |                                                                |

## Usage

There's no need to explicitly configure drivers when using ActorCore with Cloudflare Workers. The platform package automatically sets up the appropriate drivers.

See the [Cloudflare Workers Platform](/platforms/cloudflare-workers) documentation for complete setup instructions.

## Limitations

The Cloudflare Workers driver has several limitations to be aware of:

* **Storage Limits**: Storage is limited to Cloudflare's Durable Objects size limits
* **Cost**: Requires Cloudflare Workers Paid plan for Durable Objects usage
* **Platform Lock-in**: Your implementation will be specific to the Cloudflare Workers platform

<Tip>
  For a platform-agnostic approach with similar global distribution capabilities, consider using [Rivet](/platforms/rivet) instead.
</Tip>


# File System
Source: https://actorcore.org/drivers/file-system



The File System Driver is a simple file-based implementation designed for development and testing environments. It stores all actor state in local files, providing persistence between application restarts.

<Info>
  You rarely need to manually configure drivers. The platform package you're using will configure the appropriate drivers for you. See the documentation for your platform for details.
</Info>

<Warning>
  The File System Driver is primarily intended for development and testing. For production environments, consider more robust options like Rivet or Cloudflare Workers.
</Warning>

## Compatibility

| Platforms                                                              | Topologies                                                     |
| ---------------------------------------------------------------------- | -------------------------------------------------------------- |
| <Icon icon="check" iconType="solid" /> Node.js                         | <Icon icon="check" iconType="solid" /> Standalone              |
| <Icon icon="check" iconType="solid" /> Bun                             | <Icon icon="xmark" iconType="solid" color="gray" /> Partition  |
| <Icon icon="xmark" iconType="solid" color="gray" /> Cloudflare Workers | <Icon icon="xmark" iconType="solid" color="gray" /> Coordinate |
| <Icon icon="xmark" iconType="solid" color="gray" /> Rivet              |                                                                |

## Installation

<Steps>
  <Step>
    Install the required packages:

    <Tabs>
      <Tab title="npm">
        ```bash
        npm install @actor-core/file-system @actor-core/nodejs
        ```
      </Tab>

      <Tab title="yarn">
        ```bash
        yarn add @actor-core/file-system @actor-core/nodejs
        ```
      </Tab>

      <Tab title="pnpm">
        ```bash
        pnpm add @actor-core/file-system @actor-core/nodejs
        ```
      </Tab>

      <Tab title="bun">
        ```bash
        bun add @actor-core/file-system @actor-core/nodejs
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    Create a simple server using the File System driver:

    ```typescript src/index.ts
    import { serve } from "@actor-core/nodejs"
    import { FileSystemManagerDriver, FileSystemActorDriver, FileSystemGlobalState } from "@actor-core/file-system";

    const fsState = new FileSystemGlobalState();
    serve(app, {
      topology: "standalone",
      drivers: {
        manager: new FileSystemManagerDriver(app, fsState),
        actor: new FileSystemActorDriver(fsState),
      },
    });
    ```
  </Step>

  <Step>
    Start your server:

    <Tabs>
      <Tab title="npm">
        ```bash
        npm run dev
        ```
      </Tab>

      <Tab title="yarn">
        ```bash
        yarn dev
        ```
      </Tab>

      <Tab title="pnpm">
        ```bash
        pnpm dev
        ```
      </Tab>

      <Tab title="bun">
        ```bash
        bun dev
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Features

The File System driver provides several benefits for development:

* **Persistence**: Actor state is stored in files and persists between application restarts
* **Durability**: Data is written to disk, providing protection against process crashes
* **Visibility**: State files can be inspected for debugging purposes
* **No External Dependencies**: Doesn't require additional services like Redis

## Limitations

The File System driver has several limitations to be aware of:

* **Single Machine**: Only works within a single machine - not suitable for distributed environments
* **Scalability**: Limited scalability beyond a single instance
* **Coordination**: Limited support for coordinated topology
* **Performance**: File I/O operations may be slower than in-memory alternatives

<Tip>
  For production environments or applications requiring distributed capabilities, consider using the [Rivet](/platforms/rivet) or [Cloudflare Workers](/platforms/cloudflare-workers) instead.
</Tip>


# Memory
Source: https://actorcore.org/drivers/memory



The Memory Driver is a simple in-memory implementation designed for development and testing environments. It stores all actor state in memory, which means data is not persisted between application restarts.

<Info>
  You rarely need to manually configure drivers. The platform package you're using will configure the appropriate drivers for you. See the documentation for your platform for details.
</Info>

<Warning>
  The Memory Driver is not recommended for production environments as it doesn't provide persistence or distributed capabilities.
</Warning>

## Compatibility

| Platforms                                                              | Topologies                                                     |
| ---------------------------------------------------------------------- | -------------------------------------------------------------- |
| <Icon icon="check" iconType="solid" /> Node.js                         | <Icon icon="check" iconType="solid" /> Standalone              |
| <Icon icon="check" iconType="solid" /> Bun                             | <Icon icon="xmark" iconType="solid" color="gray" /> Partition  |
| <Icon icon="xmark" iconType="solid" color="gray" /> Cloudflare Workers | <Icon icon="xmark" iconType="solid" color="gray" /> Coordinate |
| <Icon icon="xmark" iconType="solid" color="gray" /> Rivet              |                                                                |

## Installation

<Steps>
  <Step>
    Install the required packages:

    <Tabs>
      <Tab title="npm">
        ```bash
        npm install @actor-core/memory @actor-core/nodejs
        ```
      </Tab>

      <Tab title="yarn">
        ```bash
        yarn add @actor-core/memory @actor-core/nodejs
        ```
      </Tab>

      <Tab title="pnpm">
        ```bash
        pnpm add @actor-core/memory @actor-core/nodejs
        ```
      </Tab>

      <Tab title="bun">
        ```bash
        bun add @actor-core/memory @actor-core/nodejs
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    Create a simple server using the Memory driver:

    ```typescript src/index.ts
    import { serve } from "@actor-core/nodejs"
    import { MemoryManagerDriver, MemoryActorDriver, MemoryGlobalState } from "@actor-core/memory";

    const memoryState = new MemoryGlobalState();
    serve(app, {
      topology: "standalone",
      drivers: {
        manager: new MemoryManagerDriver(app, memoryState),
        actor: new MemoryActorDriver(memoryState),
      },
    });
    ```
  </Step>

  <Step>
    Start your server:

    <Tabs>
      <Tab title="npm">
        ```bash
        npm run dev
        ```
      </Tab>

      <Tab title="yarn">
        ```bash
        yarn dev
        ```
      </Tab>

      <Tab title="pnpm">
        ```bash
        pnpm dev
        ```
      </Tab>

      <Tab title="bun">
        ```bash
        bun dev
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Limitations

The Memory driver has several limitations to be aware of:

* **No Persistence**: All data is stored in memory and lost when the application restarts
* **Single Process**: Only works within a single process - not suitable for distributed environments
* **Scalability**: Cannot scale beyond a single instance
* **Coordination**: Limited support for coordinated topology, as actors can only communicate within the same process

<Tip>
  For production environments or applications requiring persistence and distributed capabilities, consider using the [Rivet](/platforms/rivet) or [Cloudflare Workers](/platforms/cloudflare-workers) instead.
</Tip>


# Drivers
Source: https://actorcore.org/drivers/overview



Drivers in ActorCore the infrastructure layer between your actor code and the underlying systems.

<Info>
  You rarely need to manually configure drivers. The platform package you're using will configure the appropriate drivers for you. See the documentation for your platform for details.
</Info>

## Accessing Driver Context

Drivers expose a custom driver context for functionality specific to the given driver. This can be accessed as a parameter to `createVars` then later accessed with `c.vars`. Read more about the [`createVars` lifecycle hook](/concepts/lifecycle).

## Available Drivers

Choose a driver based on your deployment needs - [Memory](/drivers/memory) for development, [Rivet](/drivers/rivet) or [Cloudflare Workers](/drivers/cloudflare-workers) for production environments, and [Redis](/drivers/redis) for specialized self-hosted scenarios.

<CardGroup>
  <Card title="File System" href="/drivers/file-system">
    Local file system driver for development and testing with persistent storage. Stores actor state in files for durability between restarts.
  </Card>

  <Card title="Memory" href="/drivers/memory">
    In-memory driver for development and testing. Simple and lightweight with no external dependencies.
  </Card>

  <Card title="Redis" href="/drivers/redis">
    Self-hosted option for custom deployments where you need fine-grained control over your infrastructure. Suitable for specialized deployment scenarios.
  </Card>

  <Card title="Rivet" href="/drivers/rivet">
    Fully-managed cloud platform with built-in scaling, deployment, and monitoring. Recommended for production deployments.
  </Card>

  <Card title="Cloudflare Workers" href="/drivers/cloudflare-workers">
    Edge computing platform for global distribution and low latency. Recommended for production deployments.
  </Card>
</CardGroup>


# Redis
Source: https://actorcore.org/drivers/redis



The Redis Driver is a production-ready implementation that uses Redis for actor state persistence, coordination, and communication. It supports distributed actor systems and enables horizontal scaling across multiple instances.

<Info>
  You rarely need to manually configure drivers. The platform package you're using will configure the appropriate drivers for you. See the documentation for your platform for details.
</Info>

<Warning>
  ActorCore requires AOF (Append Only File) persistence to be enabled on your Redis server. See the [Redis Persistence Documentation](https://redis.io/docs/latest/operate/oss_and_stack/management/persistence/#append-only-file) for setup instructions.
</Warning>

## Compatibility

| Platforms                                                              | Topologies                                                    |
| ---------------------------------------------------------------------- | ------------------------------------------------------------- |
| <Icon icon="check" iconType="solid" /> Node.js                         | <Icon icon="check" iconType="solid" /> Standalone             |
| <Icon icon="check" iconType="solid" /> Bun                             | <Icon icon="check" iconType="solid" /> Coordinate             |
| <Icon icon="xmark" iconType="solid" color="gray" /> Cloudflare Workers | <Icon icon="xmark" iconType="solid" color="gray" /> Partition |
| <Icon icon="xmark" iconType="solid" color="gray" /> Rivet              |                                                               |

## Installation

<Steps>
  <Step>
    Install the required packages:

    <Tabs>
      <Tab title="npm">
        ```bash
        npm install @actor-core/redis @actor-core/nodejs ioredis
        ```
      </Tab>

      <Tab title="yarn">
        ```bash
        yarn add @actor-core/redis @actor-core/nodejs ioredis
        ```
      </Tab>

      <Tab title="pnpm">
        ```bash
        pnpm add @actor-core/redis @actor-core/nodejs ioredis
        ```
      </Tab>

      <Tab title="bun">
        ```bash
        bun add @actor-core/redis @actor-core/nodejs ioredis
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step>
    Create a Redis connection and set up your server:

    ```typescript src/index.ts
    import { serve } from "@actor-core/nodejs"
    import { RedisManagerDriver } from "@actor-core/redis/manager";
    import { RedisActorDriver } from "@actor-core/redis/actor";
    import { RedisCoordinateDriver } from "@actor-core/redis/coordinate";
    import Redis from "ioredis";

    // Create a Redis connection
    const redis = new Redis();

    serve(app, {
      topology: "coordinate", // Can be "standalone" or "coordinate"
      drivers: {
        manager: new RedisManagerDriver(redis),
        actor: new RedisActorDriver(redis),
        coordinate: new RedisCoordinateDriver(redis),
      },
    });
    ```
  </Step>

  <Step>
    Start your server:

    <Tabs>
      <Tab title="npm">
        ```bash
        npm run dev
        ```
      </Tab>

      <Tab title="yarn">
        ```bash
        yarn dev
        ```
      </Tab>

      <Tab title="pnpm">
        ```bash
        pnpm dev
        ```
      </Tab>

      <Tab title="bun">
        ```bash
        bun dev
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Redis Configuration

The Redis driver requires an [ioredis](https://github.com/redis/ioredis) connection instance when creating the drivers. Custom configuration parameters can be passed like:

```typescript
import Redis from "ioredis";
import { RedisManagerDriver } from "@actor-core/redis/manager";
import { RedisActorDriver } from "@actor-core/redis/actor";
import { RedisCoordinateDriver } from "@actor-core/redis/coordinate";

// Create a Redis connection
const redis = new Redis({
  host: "localhost",
  port: 6379,
  password: "foobar",
});

// Create the Redis drivers
const managerDriver = new RedisManagerDriver(redis);
const actorDriver = new RedisActorDriver(redis);
const coordinateDriver = new RedisCoordinateDriver(redis);
```

<Info>
  See the [ioredis documentation](https://github.com/redis/ioredis#connect-to-redis) for more connection configuration options.
</Info>

## Hosted Redis Providers

For production deployments, consider using these managed Redis providers:

* [Amazon ElastiCache](https://aws.amazon.com/elasticache/) - AWS managed Redis service
* [Azure Cache for Redis](https://azure.microsoft.com/en-us/products/cache) - Microsoft Azure managed Redis service
* [Google Cloud Memorystore](https://cloud.google.com/memorystore) - Google Cloud managed Redis service
* [Upstash](https://upstash.com/) - Serverless Redis with pay-per-use pricing
* [Redis Cloud](https://redis.com/redis-enterprise-cloud/overview/) - Official Redis offering with enterprise features
* [Dragonfly](https://www.dragonflydb.io/) - Redis-compatible database with higher performance

<Callout>
  For local development where persistence isn't required, the [Memory Driver](/drivers/memory) offers a simpler setup with no external dependencies.
</Callout>

## Limitations

The Redis driver has several limitations to be aware of:

* **Very Limited Storage**: Storage is limited to the available memory of your Redis server
* **Single Region Support**: Only supports deployment within a single region, not globally distributed
* **Performance Bottleneck**: All operations go through Redis, which can become a bottleneck under high load
* **Single Point of Failure**: Redis becomes a single point of failure if not configured with proper failover mechanisms

<Tip>
  For multi-region support, built-in redundancy, and unlimited storage capacity, consider using [Rivet](/platforms/rivet) or [Cloudflare Workers](/platforms/cloudflare-workers) instead.
</Tip>


# Rivet
Source: https://actorcore.org/drivers/rivet



The Rivet Driver is a production-ready implementation that uses Rivet's managed infrastructure for actor state persistence, coordination, and communication. It provides a fully managed environment for ActorCore with built-in scaling, monitoring, and global distribution.

<Info>
  You rarely need to manually configure drivers. The platform package you're using will configure the appropriate drivers for you. See the documentation for your platform for details.
</Info>

## Compatibility

| Platforms                                                              | Topologies                                                     |
| ---------------------------------------------------------------------- | -------------------------------------------------------------- |
| <Icon icon="xmark" iconType="solid" color="gray" /> Node.js            | <Icon icon="xmark" iconType="solid" color="gray" /> Standalone |
| <Icon icon="xmark" iconType="solid" color="gray" /> Bun                | <Icon icon="xmark" iconType="solid" color="gray" /> Coordinate |
| <Icon icon="xmark" iconType="solid" color="gray" /> Cloudflare Workers | <Icon icon="check" iconType="solid" /> Partition               |
| <Icon icon="check" iconType="solid" /> Rivet                           |                                                                |

## Usage

There's no need to explicitly configure drivers when using ActorCore with Rivet. The platform package automatically sets up the appropriate drivers based on your project configuration.

See the [Rivet Platform](/platforms/rivet) documentation for complete setup instructions.

## Benefits

The Rivet driver offers several advantages:

* **Fully Managed**: No infrastructure to provision or maintain
* **Global Distribution**: Deploy actors globally with automatic region selection
* **Monitoring**: Built-in observability and performance metrics
* **Cost Efficiency**: Pay only for what you use with no upfront costs
* **Partition Topology Support**: Optimized for the Partition topology for efficient scaling

<Tip>
  Rivet is a great choice for production deployments, offering enterprise-grade reliability without the operational overhead.
</Tip>


# React
Source: https://actorcore.org/frameworks/react



Learn how to create realtime, stateful React applications with ActorCore's actor model.

<Info>
  ActorCore is still pre-v1.0. Please help us by report bugs on [GitHub Issues](https://github.com/rivet-gg/actor-core/issues)!
</Info>

## Quickstart

<Steps>
  <Step title="Create a new React project">
    Create a new React project with TypeScript support:

    <CodeGroup>
      ```sh npm
      npm create vite@latest my-app -- --template react-ts
      ```

      ```sh pnpm
      pnpm create vite@latest my-app --template react-ts
      ```

      ```sh yarn
      yarn create vite my-app --template react-ts
      ```

      ```sh bun
      bunx create-vite@latest my-app --template react-ts
      ```
    </CodeGroup>
  </Step>

  <Step title="Install ActorCore packages">
    Navigate to your React project and install the ActorCore client and React packages:

    <CodeGroup>
      ```sh npm
      cd my-app
      npm install actor-core @actor-core/react
      ```

      ```sh pnpm
      cd my-app
      pnpm add actor-core @actor-core/react
      ```

      ```sh yarn
      cd my-app
      yarn add actor-core @actor-core/react
      ```

      ```sh bun
      cd my-app
      bun add actor-core @actor-core/react
      ```
    </CodeGroup>
  </Step>

  <Step title="Define your actor">
    Create a file `actors/app.ts` in your project with your actor definition:

    ```typescript actors/app.ts
    import { actor, setup } from "actor-core";

    // Create actor
    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;
        }
      }
    });

    // Create the application
    export const app = setup({
      actors: { counter },
      cors: { origin: "*" } // Configure CORS for your production domains in production
    });

    // Export app type for client usage
    export type App = typeof app;
    ```
  </Step>

  <Step title="Build your React frontend">
    Now modify your `src/App.tsx` file to connect to your ActorCore backend:

    ```tsx src/App.tsx
    import { createClient } from "actor-core/client";
    import { createReactActorCore } from "@actor-core/react";
    import type { App } from "../actors/app";
    import React, { useState } from "react";

    // Replace with your endpoint URL after deployment
    const client = createClient<App>("http://localhost:6420");
    const { useActor, useActorEvent } = createReactActorCore(client);

    function App() {
      // Connect to counter actor
      const [{ actor }] = useActor("counter");
      const [count, setCount] = useState(0);
      
      // Listen to count updates
      useActorEvent({ actor, event: "newCount" }, (newCount) => {
        setCount(newCount);
      });

      return (
        <div>
          <p>Count: {count}</p>
          <button 
            onClick={() => actor?.increment(1)}
            disabled={!actor}
          >
            Increment
          </button>
        </div>
      );
    }

    // For Vite + React 18
    import { createRoot } from 'react-dom/client';
    const root = createRoot(document.getElementById('root')!);
    root.render(<App />);
    ```
  </Step>

  <Step title="Start your ActorCore development server">
    Launch the development server with:

    <CodeGroup>
      ```sh npm
      npx @actor-core/cli@latest dev actors/app.ts
      ```

      ```sh pnpm
      pnpm exec @actor-core/cli@latest dev actors/app.ts
      ```

      ```sh yarn
      yarn @actor-core/cli@latest dev actors/app.ts
      ```

      ```sh bun
      bunx @actor-core/cli@latest dev actors/app.ts
      ```
    </CodeGroup>

    This will automatically start your app and open the studio in your browser. The studio supports hot-reloading, state inspection, visual RPC testing, and more debugging tools.

    ![ActorCore Studio](https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/screenshots/studio/simple.png)
  </Step>

  <Step title="Start your React app">
    In a separate terminal, start your React app:

    <CodeGroup>
      ```sh npm
      cd my-app
      npm run dev
      ```

      ```sh pnpm
      cd my-app
      pnpm run dev
      ```

      ```sh yarn
      cd my-app
      yarn dev
      ```

      ```sh bun
      cd my-app
      bun run dev
      ```
    </CodeGroup>

    Your React app should now be running and connected to your ActorCore backend. Open your browser to the URL shown in the terminal (typically [http://localhost:5173](http://localhost:5173)) to see your application.
  </Step>

  <Step title="Deploy your ActorCore app">
    Now that you have your project running, deploy your application to one of these platforms:

    <CardGroup cols={2}>
      <Card title="Rivet" href="/platforms/rivet" />

      <Card title="Cloudflare Workers" href="/platforms/cloudflare-workers" />

      <Card title="Bun" href="/platforms/bun" />

      <Card title="Node.js" href="/platforms/nodejs" />
    </CardGroup>
  </Step>
</Steps>

## API Reference

The React integration leverages React's hooks system to provide an idiomatic way to interact with ActorCore in React applications.

### `createReactActorCore`

The main function that creates React hooks for interacting with ActorCore. It takes a client instance and returns hook functions.

```tsx
const { useActor, useActorEvent } = createReactActorCore(client);
```

#### Parameters

* `client`: The ActorCore client created with `createClient`.

#### Returns

An object containing React hooks:

* `useActor`: Hook for connecting to actors
* `useActorEvent`: Hook for subscribing to actor events

### `useActor`

Hook that connects to an actor, creating it if necessary. It manages the actor connection and returns the actor handle.

```tsx
const [{ actor, error, isLoading, state }] = useActor(actorName, options);
```

#### Parameters

* `actorName`: The name of the actor to connect to (string).
* `options`: Optional connection options (same options as `client.actorName.get()`).
  * `id`: String identifier for the actor instance.
  * `tags`: Key-value pairs for actor identification.
  * `params`: Parameters to pass during connection.
  * `noCreate`: Boolean to prevent actor creation if it doesn't exist.

#### Returns

Returns an array with a single object containing:

* `actor`: The actor handle if connected, or `undefined` if still connecting.
* `error`: Any error that occurred during connection.
* `isLoading`: Boolean indicating if the connection is in progress.
* `state`: String representing the internal connection state ("init", "creating", "created", or "error").

### `useActorEvent`

Hook that subscribes to events from an actor.

```tsx
useActorEvent({ actor, event }, cb);
```

#### Parameters

* `opts`: Object containing:
  * `actor`: The actor handle from `useActor`, or undefined.
  * `event`: The name of the event to subscribe to.
* `cb`: Function called when the event is fired. The arguments passed to this function depend on the event type.

#### Returns

This hook doesn't return a value. The subscription is automatically managed by the hook lifecycle.

## Example Usage

### Simple Counter

```tsx
import { createClient } from "actor-core/client";
import { createReactActorCore } from "@actor-core/react";
import type { App } from "../actors/app";
import { useState } from "react";

// Connect to ActorCore
const client = createClient<App>("http://localhost:6420");
const { useActor, useActorEvent } = createReactActorCore(client);

function Counter() {
  // Get actor and track count
  const [{ actor }] = useActor("counter");
  const [count, setCount] = useState(0);
  
  // Listen for count updates
  useActorEvent({ actor, event: "newCount" }, setCount);
  
  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => actor?.increment(1)} disabled={!actor}>
        Increment
      </button>
    </div>
  );
}
```

## Next Steps

<CardGroup>
  <Card title="Overview" href="/concepts/overview" icon="square-plus" horizontal={true} />

  <Card title="Interacting with Actors" href="/concepts/interacting-with-actors" icon="square-plus" horizontal={true} />

  <Card title="Actions" href="/concepts/actions" icon="bolt" horizontal={true} />

  <Card title="State" href="/concepts/state" icon="floppy-disk" horizontal={true} />
</CardGroup>


# Hono
Source: https://actorcore.org/integrations/hono



[Hono](https://hono.dev/) is a lightweight web framework that works well with ActorCore across multiple deployment platforms. This guide explains how to integrate ActorCore with Hono on different platforms.

## Mounting The ActorCore Router

When mounting the ActorCore router at a custom path, you **must** specify the same path in the router configuration using `basePath`:

```typescript
// Setup the ActorCore app
const app = setup({
  actors: { counter },
  // IMPORTANT: Must specify the same basePath where your router is mounted
  basePath: "/my-path"
});

// Create a router from the app
const { router: actorRouter } = createRouter(app);

// Mount at the same path specified in basePath
honoApp.route("/my-path", actorRouter);
```

This ensures that WebSocket connections and other functionality work correctly when accessing your actors through the custom path.

## Platform-Specific Examples

Each platform has specific requirements for integrating Hono with ActorCore.

### Cloudflare Workers

```typescript
import { createRouter } from "@actor-core/cloudflare-workers";
import { setup } from "actor-core";
import { Hono } from "hono";
import counter from "./counter";

// Create your Hono app inside the fetch handler
const honoApp = new Hono();

// Add your custom routes
honoApp.get("/", (c) => c.text("Welcome to my app!"));
honoApp.get("/hello", (c) => c.text("Hello, world!"));

// Setup the ActorCore app
const app = setup({
  actors: { counter },
  // IMPORTANT: Must specify the same basePath where your router is mounted
  basePath: "/my-path"
});

// Create a router and handler from the app
const { router: actorRouter, ActorHandler } = createRouter(app);

// Mount the ActorCore router at /my-path
honoApp.route("/my-path", actorRouter);

// Export the app type for client usage
export type App = typeof app;

// IMPORTANT: Must export `ActorHandler` as this exact name
export { honoApp as default, ActorHandler };
```

Make sure to update your client connection URL to include the custom path:

```typescript
// If you mounted ActorCore at /my-path
import { createClient } from "actor-core/client";
import type { App } from "./src/index";

const client = createClient<App>("https://your-worker.workers.dev/my-path");
```

For this to work with Cloudflare Workers, your `wrangler.json` **must** include specific Durable Object and KV namespace bindings with the exact names expected by ActorCore:

```json
{
  "name": "counter",
  "main": "src/index.ts",
  "compatibility_date": "2025-01-29",
  "migrations": [
    {
      "new_classes": ["ActorHandler"],
      "tag": "v1"
    }
  ],
  "durable_objects": {
    "bindings": [
      {
        "class_name": "ActorHandler", // Must match exported class
        "name": "ACTOR_DO"            // Must use this exact name
      }
    ]
  },
  "kv_namespaces": [
    {
      "binding": "ACTOR_KV",          // Must use this exact name
      "id": "YOUR_KV_NAMESPACE_ID"    // Replace with your KV ID
    }
  ]
}
```

### Node.js

```typescript
import { serve } from "@hono/node-server";
import { Hono } from "hono";
import { setup, createRouter } from "@actor-core/nodejs";
import counter from "./counter";

// Create your Hono app
const honoApp = new Hono();

// Add your custom routes
honoApp.get("/", (c) => c.text("Welcome to my app!"));
honoApp.get("/hello", (c) => c.text("Hello, world!"));

// Setup the ActorCore app
const app = setup({
  actors: { counter },
  // IMPORTANT: Must specify the same basePath where your router is mounted
  basePath: "/my-path"
});

// Create a router from the app
const { router: actorRouter, injectWebSocket } = createRouter(app);

// Mount the ActorCore router at /my-path
honoApp.route("/my-path", actorRouter);

// Export the app type for client usage
export type App = typeof app;

// Create server with the combined app
const server = serve({
  fetch: honoApp.fetch,
  port: 6420,
});

// IMPORTANT: Inject the websocket handler into the server
injectWebSocket(server);

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

Make sure to update your client connection URL to include the custom path:

```typescript
// If you mounted ActorCore at /my-path
import { createClient } from "actor-core/client";
import type { App } from "./src/index";

const client = createClient<App>("http://localhost:6420/my-path");
```

### Bun

```typescript
import { Hono } from "hono";
import { setup, createRouter } from "@actor-core/bun";
import counter from "./counter";

// Create your Hono app
const honoApp = new Hono();

// Add your custom routes
honoApp.get("/", (c) => c.text("Welcome to my app!"));
honoApp.get("/hello", (c) => c.text("Hello, world!"));

// Setup the ActorCore app
const app = setup({
  actors: { counter },
  // IMPORTANT: Must specify the same basePath where your router is mounted
  basePath: "/my-path"
});

// Create a router from the app
const { router: actorRouter, webSocketHandler } = createRouter(app);

// Mount the ActorCore router at /my-path
honoApp.route("/my-path", actorRouter);

// Export the app type for client usage
export type App = typeof app;

// Create and start the server
export default {
  port: 6420,
  fetch: honoApp.fetch,
  // IMPORTANT: Pass the webSocketHandler to Bun
  websocket: webSocketHandler,
};
```

Make sure to update your client connection URL to include the custom path:

```typescript
// If you mounted ActorCore at /my-path
import { createClient } from "actor-core/client";
import type { App } from "./src/index";

const client = createClient<App>("http://localhost:6420/my-path");
```


# All Integrations
Source: https://actorcore.org/integrations/overview



## Integrations

<CardGroup>
  <Card title="Hono" href="/integrations/hono" />

  <Card title="Resend" href="/integrations/resend" />
</CardGroup>

## Drivers

<CardGroup>
  <Card title="Overview" href="/drivers/overview" />

  <Card title="File System" href="/drivers/file-system" />

  <Card title="Memory" href="/drivers/memory" />

  <Card title="Redis" href="/drivers/redis" />

  <Card title="Rivet" href="/drivers/rivet" />

  <Card title="Durable Objects" href="/drivers/cloudflare-workers" />

  <Card title="Building Drivers" href="/drivers/build" />
</CardGroup>


# Resend
Source: https://actorcore.org/integrations/resend



[Resend](https://resend.com) is an email API service that works seamlessly with ActorCore for handling emails and notifications.

## Example

See how ActorCore and Resend can power engagement with daily streak notifications.

<Card icon="fire" title="Streaks" href="https://github.com/rivet-gg/actor-core/tree/main/examples/resend-streaks">View on GitHub</Card>

## Quickstart

<Steps>
  <Step title="Install Resend SDK">
    ```bash
    npm install resend
    ```
  </Step>

  <Step title="Create an actor with Resend">
    ```typescript actors.ts
    import { actor, setup } from "actor-core";
    import { Resend } from "resend";

    const resend = new Resend(process.env.RESEND_API_KEY);

    const user = actor({
      state: {
        email: null as string | null,
      },

      actions: {
        // Example: Somehow acquire the user's email
        register: async (c, email: string) => {
          c.state.email = email;
        },

        // Example: Send an email
        sendExampleEmail: async (c) => {
          if (!c.state.email) throw new Error("No email registered");
          
          await resend.emails.send({
            from: "updates@yourdomain.com",
            to: c.state.email,
            subject: "Hello, world!",
            html: "<p>Lorem ipsum</p>",
          });
        },
      },
    });

    export const app = setup({ actors: { user } });
    export type App = typeof app;
    ```
  </Step>

  <Step title="Call your actor">
    ```typescript client.ts
    import { createClient } from "actor-core";
    import { App } from "./actors/app.ts";

    const client = createClient<App>("http://localhost:8787");
    const userActor = await client.user.get({ tags: { user: "user123" } });

    await userActor.register("user@example.com");
    await userActor.sendExampleEmail();
    ```
  </Step>
</Steps>

## Use Cases

### Scheduling Emails

ActorCore's scheduling capabilities with Resend make it easy to send emails at specific times:

<CodeGroup>
  ```typescript actors.ts
  const emailScheduler = actor({
    state: {
      email: null as string | null,
    },

    actions: {
      scheduleEmail: async (c, email: string, delayMs: number = 86400000) => {
        c.state.email = email;
        await c.schedule.at(Date.now() + delayMs, "sendEmail");
      },
      
      sendEmail: async (c) => {
        if (!c.state.email) return;
        
        await resend.emails.send({
          from: "updates@yourdomain.com",
          to: c.state.email,
          subject: "Your scheduled message",
          html: "<p>This email was scheduled earlier!</p>",
        });
      },
    },
  });
  ```

  ```typescript client.ts
  const client = createClient<App>({ url: "http://localhost:3000" });
  const scheduler = await client.emailScheduler.get({ id: "user123" });
  await scheduler.scheduleEmail("user@example.com", 60000); // 1 minute
  ```
</CodeGroup>

### Daily Reminders

Send daily reminders to users based on their activity:

<CodeGroup>
  ```typescript actors.ts
  const reminder = actor({
    state: {
      email: null as string | null,
      lastActive: null as number | null,
    },

    actions: {
      trackActivity: async (c, email: string) => {
        c.state.email = email;
        c.state.lastActive = Date.now();
        
        // Schedule check for tomorrow
        await c.schedule.at(Date.now() + 24 * 60 * 60 * 1000, "checkActivity");
      },
      
      checkActivity: async (c) => {
        if (!c.state.email) return;
        
        // If inactive for 24+ hours, send reminder
        if (Date.now() - (c.state.lastActive || 0) >= 24 * 60 * 60 * 1000) {
          await resend.emails.send({
            from: "reminders@yourdomain.com",
            to: c.state.email,
            subject: "We miss you!",
            html: "<p>Don't forget to check in today.</p>",
          });
        }
        
        // Reschedule for tomorrow
        await c.schedule.at(Date.now() + 24 * 60 * 60 * 1000, "checkActivity");
      },
    },
  });
  ```

  ```typescript client.ts
  const client = createClient<App>({ url: "http://localhost:3000" });
  const userReminder = await client.reminder.get({ id: "user123" });
  await userReminder.trackActivity("user@example.com");
  ```
</CodeGroup>

### Alerting Systems

Monitor your systems and send alerts when issues are detected:

<CodeGroup>
  ```typescript actors.ts
  const monitor = actor({
    state: {
      alertEmail: null as string | null,
      isHealthy: true,
    },

    actions: {
      configure: async (c, email: string) => {
        c.state.alertEmail = email;
        await c.schedule.at(Date.now() + 60000, "checkHealth");
      },
      
      checkHealth: async (c) => {
        // Simple mock health check
        const wasHealthy = c.state.isHealthy;
        c.state.isHealthy = await mockHealthCheck();
        
        // Alert on status change to unhealthy
        if (wasHealthy && !c.state.isHealthy && c.state.alertEmail) {
          await resend.emails.send({
            from: "alerts@yourdomain.com",
            to: c.state.alertEmail,
            subject: "⚠️ System Alert",
            html: "<p>The system is experiencing issues.</p>",
          });
        }
        
        // Reschedule next check
        await c.schedule.at(Date.now() + 60000, "checkHealth");
      },
    },
  });

  // Mock function
  async function mockHealthCheck() {
    return Math.random() > 0.1; // 90% chance of being healthy
  }
  ```

  ```typescript client.ts
  const client = createClient<App>({ url: "http://localhost:3000" });
  const systemMonitor = await client.monitor.get({ id: "api-service" });
  await systemMonitor.configure("admin@example.com");
  ```
</CodeGroup>

## Testing

When testing actors that use Resend, you should mock the Resend API to avoid sending real emails during tests. ActorCore's testing utilities combined with Vitest make this straightforward:

```typescript
import { test, expect, vi, beforeEach } from "vitest";
import { setupTest } from "actor-core/test";
import { app } from "../actors/app";

// Create mock for send method
const mockSendEmail = vi.fn().mockResolvedValue({ success: true });

beforeEach(() => {
  process.env.RESEND_API_KEY = "test_mock_api_key_12345";

  vi.mock("resend", () => {
    return {
      Resend: vi.fn().mockImplementation(() => {
        return {
          emails: {
            send: mockSendEmail
          }
        };
      })
    };
  });

  mockSendEmail.mockClear();
});

test("email is sent when action is called", async (t) => {
  const { client } = await setupTest(t, app);
  const actor = await client.user.get();

  // Call the action that should send an email
  await actor.someActionThatSendsEmail("user@example.com");

  // Verify the email was sent with the right parameters
  expect(mockSendEmail).toHaveBeenCalledWith(
    expect.objectContaining({
      to: "user@example.com",
      subject: "Expected Subject",
    }),
  );
});
```

Using `vi.advanceTimersByTimeAsync()` is particularly useful for testing scheduled emails:

```typescript
// Fast forward time to test scheduled emails
await vi.advanceTimersByTimeAsync(24 * 60 * 60 * 1000); // Advance 24 hours

// Test that the scheduled email was sent
expect(mockSendEmail).toHaveBeenCalledTimes(2);
```


# ActorCore
Source: https://actorcore.org/introduction

Stateful Serverless That Runs Anywhere

<div className="particle-container" />

<div className="landing-root">
  <div className="landing-hero landing-section">
    <h1 className="landing-title">
      Stateful Serverless That Runs Anywhere
    </h1>

    <p className="landing-subtitle">
      The easiest way to build{" "}
      <span className="landing-subtitle-highlight">stateful</span>,{" "}
      <span className="landing-subtitle-highlight">AI agent</span>,{" "}
      <span className="landing-subtitle-highlight">collaborative</span>, or{" "}
      <span className="landing-subtitle-highlight">local-first</span>{" "}
      applications.<br />
      Deploy to Rivet, Cloudflare, Bun, Node.js, and more.
    </p>

    <div className="landing-buttons">
      <a href="/overview" className="landing-button landing-button-primary">
        Get Started
      </a>

      <a href="https://github.com/rivet-gg/actor-core" className="landing-button landing-button-secondary" target="_blank" rel="noopener noreferrer">
        View on GitHub
      </a>
    </div>

    <div className="copy-command-container" onClick={(e) => window.copyCommand && window.copyCommand(e.currentTarget)}>
      <div className="copy-command-icon">
        <Icon icon="arrow-right" iconType="solid" color="white" />
      </div>

      <div className="copy-command-text">npx create-actor\@latest</div>

      <div className="icon-container">
        <div className="copy-icon">
          <Icon icon="copy" />
        </div>

        <div className="check-icon">
          <Icon icon="check" />
        </div>
      </div>
    </div>

    <div style={{ height: '50px' }} />

    <div className="features-grid">
      <div className="feature-box group">
        <Icon icon="microchip" color="#ff4f00" size={24} />

        <h3 className="not-prose">Long-Lived, Stateful Compute</h3>

        <div className="feature-description">
          <p>Each unit of compute is like a tiny server that remembers things between requests – no need to reload data or worry about timeouts. Like AWS Lambda, but with memory and no timeouts.</p>
        </div>
      </div>

      <div className="feature-box group">
        <Icon icon="database" color="#ff4f00" size={24} />

        <h3 className="not-prose">Durable State Without a Database</h3>

        <div className="feature-description">
          <p>Your code's state is saved automatically—no database, ORM, or config needed. Just use regular JavaScript objects or SQLite (available in April).</p>
        </div>
      </div>

      <div className="feature-box group">
        <Icon icon="bolt" color="#ff4f00" size={24} />

        <h3 className="not-prose">Blazing-Fast Reads & Writes</h3>

        <div className="feature-description">
          <p>State is stored on the same machine as your compute, so reads and writes are ultra-fast. No database round trips, no latency spikes.</p>
        </div>
      </div>

      <div className="feature-box group">
        <Icon icon="tower-broadcast" color="#ff4f00" size={24} />

        <h3 className="not-prose">Realtime, Made Simple</h3>

        <div className="feature-description">
          <p>Update state and broadcast changes in realtime. No external pub/sub systems, no polling – just built-in low-latency events.</p>
        </div>
      </div>

      <div className="feature-box group">
        <Icon icon="globe" color="#ff4f00" size={24} />

        <h3 className="not-prose">Store Data Near Your Users</h3>

        <div className="feature-description">
          <p>Your state lives close to your users on the edge – not in a faraway data center – so every interaction feels instant.</p>
        </div>
      </div>

      <div className="feature-box group">
        <Icon icon="cloud" color="#ff4f00" size={24} />

        <h3 className="not-prose">Serverless & Scalable</h3>

        <div className="feature-description">
          <p>No servers to manage. Your code runs on-demand and scales automatically with usage.</p>
        </div>
      </div>
    </div>

    <div className="subtle-link-container">
      <a href="#faq" className="subtle-link">Have more questions? Jump to our FAQ <Icon icon="arrow-right" color="white" /></a>
    </div>
  </div>

  <div style={{ height: '160px' }} />

  <div className="landing-section-xl">
    <h2 className="landing-section-heading">Reconsider What Your Backend Can Do</h2>
    <p className="landing-section-text">Build powerful applications with ActorCore's comprehensive feature set.</p>

    <div style={{ height: '20px' }} />

    <div class="code-group">
      <div class="code-group-tabs">
        {/* Scroll Bars */}

        <div class="scroll-indicators-overlay">
          <div class="scroll-indicator left">
            <Icon icon="chevron-left" color="white" size={14} />
          </div>

          <div class="scroll-indicator right">
            <Icon icon="chevron-right" color="white" size={14} />
          </div>
        </div>

        {/* Examples */}

        <div class="code-group-tab-row primary-tabs">
          <div class="code-group-tab-label">Example</div>

          <div class="code-group-tab active" data-tab="chat">
            <Icon icon="message" color="white" size={14} />

            Chat Room
          </div>

          <div class="code-group-tab" data-tab="ai">
            <Icon icon="robot" color="white" size={14} />

            AI Agent
          </div>

          <div class="code-group-tab" data-tab="sync">
            <Icon icon="rotate" color="white" size={14} />

            Local-First Sync
          </div>

          <div class="code-group-tab" data-tab="tenant">
            <Icon icon="building" color="white" size={14} />

            Per-Tenant Saas
          </div>

          <div class="code-group-tab" data-tab="database">
            <Icon icon="database" color="white" size={14} />

            Per-User Databases
          </div>

          <div class="code-group-tab" data-tab="crdt">
            <Icon icon="code-merge" color="white" size={14} />

            Yjs CRDT
          </div>

          <div class="code-group-tab" data-tab="doc">
            <Icon icon="file-pen" color="white" size={14} />

            Collaborative Document
          </div>

          <div class="code-group-tab" data-tab="stream">
            <Icon icon="wave-sine" color="white" size={14} />

            Stream Processing
          </div>

          <div class="code-group-tab" data-tab="game">
            <Icon icon="gamepad" color="white" size={14} />

            Multiplayer Game
          </div>

          <div class="code-group-tab" data-tab="rate">
            <Icon icon="gauge-high" color="white" size={14} />

            Rate Limiter
          </div>
        </div>

        {/* State */}

        <div class="code-group-tab-row secondary-tabs">
          <div class="code-group-tab-label">State</div>
          <div class="code-group-tab active" data-tab="memory">JavaScript</div>
          <div class="code-group-tab" data-tab="sqlite">SQLite<span class="code-group-coming-soon">Available In April</span></div>
        </div>
      </div>

      {/* Code */}

      <div class="code-group-panels">
        {/* Chat Room */}

        <div class="code-panel active" data-panel="chat-memory">
          <div class="code-split">
            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">actor.ts</span>
                <span class="file-description">Runs on the server</span>
              </div>

              <div class="code-block">
                ```typescript
                import { actor } from "actor-core";

                export type Message = { sender: string; text: string; timestamp: number; }

                const chatRoom = actor({
                  // State is automatically persisted
                  state: { 
                    messages: [] as Message[] 
                  },

                  actions: {
                    sendMessage: (c, sender: string, text: string) => {
                      const message = { sender, text, timestamp: Date.now() };
                      
                      // Any changes to state are automatically saved
                      c.state.messages.push(message);
                      
                      // Broadcast events trigger real-time updates in connected clients
                      c.broadcast("newMessage", message);
                    },

                    getHistory: (c) => c.state.messages
                  }
                });

                export default chatRoom;
                ```
              </div>
            </div>

            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">App.tsx</span>
                <span class="file-description">Runs in the browser</span>
              </div>

              <div class="code-block">
                ```typescript
                import { createClient } from "actor-core/client";
                import { createReactActorCore } from "@actor-core/react";
                import { useState, useEffect } from "react";
                import type { App } from "../actors/app";
                import type { Message } from "./actor";

                const client = createClient<App>("http://localhost:6420");
                const { useActor, useActorEvent } = createReactActorCore(client);

                export function ChatRoom({ roomId = "general" }) {
                  // Connect to specific chat room using tags
                  const [{ actor }] = useActor("chatRoom", { 
                    tags: { roomId }
                  });
                  
                  const [messages, setMessages] = useState<Message[]>([]);
                  const [input, setInput] = useState("");

                  // Load initial state
                  useEffect(() => {
                    if (actor) {
                      // Load chat history
                      actor.getHistory().then(setMessages);
                    }
                  }, [actor]);

                  // Listen for real-time updates from the server
                  useActorEvent({ actor, event: "newMessage" }, (message) => {
                    setMessages(prev => [...prev, message]);
                  });

                  const sendMessage = () => {
                    if (actor && input.trim()) {
                      actor.sendMessage("User", input);
                      setInput("");
                    }
                  };

                  return (
                    <div className="chat-container">
                      <div className="room-header">
                        <h3>Chat Room: {roomId}</h3>
                      </div>
                      
                      <div className="messages">
                        {messages.length === 0 ? (
                          <div className="empty-message">No messages yet. Start the conversation!</div>
                        ) : (
                          messages.map((msg, i) => (
                            <div key={i} className="message">
                              <b>{msg.sender}:</b> {msg.text}
                              <span className="timestamp">
                                {new Date(msg.timestamp).toLocaleTimeString()}
                              </span>
                            </div>
                          ))
                        )}
                      </div>
                      
                      <div className="input-area">
                        <input
                          value={input}
                          onChange={e => setInput(e.target.value)}
                          onKeyPress={e => e.key === "Enter" && sendMessage()}
                          placeholder="Type a message..."
                        />
                        <button onClick={sendMessage}>Send</button>
                      </div>
                    </div>
                  );
                }
                ```
              </div>
            </div>
          </div>
        </div>

        <div class="code-panel" data-panel="chat-sqlite">
          <div class="code-split">
            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">actor.ts</span>
                <span class="file-description">Runs on the server</span>
              </div>

              <div class="code-block">
                ```typescript
                import { actor } from "actor-core";
                import { drizzle } from "@actor-core/drizzle";
                import { messages } from "./schema";

                export type Message = { sender: string; text: string; timestamp: number; }

                const chatRoom = actor({
                  sql: drizzle(),

                  actions: {
                    sendMessage: async (c, sender: string, text: string) => {
                      const message = {
                        sender,
                        text,
                        timestamp: Date.now(),
                      };

                      // Insert the message into SQLite
                      await c.db.insert(messages).values(message);
                      
                      // Broadcast to all connected clients
                      c.broadcast("newMessage", message);
                      
                      // Return the created message (matches JS memory version)
                      return message;
                    },

                    getHistory: async (c) => {
                      // Query all messages ordered by timestamp
                      const result = await c.db
                        .select()
                        .from(messages)
                        .orderBy(messages.timestamp);
                      
                      return result as Message[];
                    }
                  }
                });

                export default chatRoom;
                ```
              </div>
            </div>

            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">App.tsx</span>
                <span class="file-description">Runs in the browser</span>
              </div>

              <div class="code-block">
                ```typescript
                import { createClient } from "actor-core/client";
                import { createReactActorCore } from "@actor-core/react";
                import { useState, useEffect } from "react";
                import type { App } from "../actors/app";
                import type { Message } from "./actor";

                const client = createClient<App>("http://localhost:6420");
                const { useActor, useActorEvent } = createReactActorCore(client);

                export function ChatRoom({ roomId = "general" }) {
                  // Connect to specific chat room using tags
                  const [{ actor }] = useActor("chatRoom", { 
                    tags: { roomId }
                  });
                  
                  const [messages, setMessages] = useState<Message[]>([]);
                  const [input, setInput] = useState("");

                  // Load initial state
                  useEffect(() => {
                    if (actor) {
                      // Load chat history
                      actor.getHistory().then(setMessages);
                    }
                  }, [actor]);

                  // Listen for real-time updates from the server
                  useActorEvent({ actor, event: "newMessage" }, (message) => {
                    setMessages(prev => [...prev, message]);
                  });

                  const sendMessage = () => {
                    if (actor && input.trim()) {
                      actor.sendMessage("User", input);
                      setInput("");
                    }
                  };

                  return (
                    <div className="chat-container">
                      <div className="room-header">
                        <h3>Chat Room: {roomId}</h3>
                      </div>
                      
                      <div className="messages">
                        {messages.length === 0 ? (
                          <div className="empty-message">No messages yet. Start the conversation!</div>
                        ) : (
                          messages.map((msg, i) => (
                            <div key={i} className="message">
                              <b>{msg.sender}:</b> {msg.text}
                              <span className="timestamp">
                                {new Date(msg.timestamp).toLocaleTimeString()}
                              </span>
                            </div>
                          ))
                        )}
                      </div>
                      
                      <div className="input-area">
                        <input
                          value={input}
                          onChange={e => setInput(e.target.value)}
                          onKeyPress={e => e.key === "Enter" && sendMessage()}
                          placeholder="Type a message..."
                        />
                        <button onClick={sendMessage}>Send</button>
                      </div>
                    </div>
                  );
                }
                ```
              </div>
            </div>
          </div>
        </div>

        {/* AI Agent */}

        <div class="code-panel" data-panel="ai-memory">
          <div class="code-split">
            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">actor.ts</span>
                <span class="file-description">Runs on the server</span>
              </div>

              <div class="code-block">
                ```typescript
                import { actor } from "actor-core";
                import { generateText, tool } from "ai";
                import { openai } from "@ai-sdk/openai";
                import { getWeather } from "./my-utils";

                export type Message = { role: "user" | "assistant"; content: string; timestamp: number; }

                const aiAgent = actor({
                  // State is automatically persisted
                  state: { 
                    messages: [] as Message[]
                  },

                  actions: {
                    // Get conversation history
                    getMessages: (c) => c.state.messages,

                    // Send a message to the AI and get a response
                    sendMessage: async (c, userMessage: string) => {
                      // Add user message to conversation
                      const userMsg: Message = { 
                        role: "user", 
                        content: userMessage,
                        timestamp: Date.now()
                      };
                      c.state.messages.push(userMsg);
                      
                      // Generate AI response using Vercel AI SDK with tools
                      const { text } = await generateText({
                        model: openai("o3-mini"),
                        prompt: userMessage,
                        messages: c.state.messages,
                        tools: {
                          weather: tool({
                            description: 'Get the weather in a location',
                            parameters: {
                              location: {
                                type: 'string',
                                description: 'The location to get the weather for',
                              },
                            },
                            execute: async ({ location }) => {
                              return await getWeather(location);
                            },
                          }),
                        },
                      });
                      
                      // Add AI response to conversation
                      const assistantMsg: Message = { 
                        role: "assistant", 
                        content: text, 
                        timestamp: Date.now() 
                      };
                      c.state.messages.push(assistantMsg);
                      
                      // Broadcast the new message to all connected clients
                      c.broadcast("messageReceived", assistantMsg);
                      
                      return assistantMsg;
                    },
                  }
                });

                export default aiAgent;
                ```
              </div>
            </div>

            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">App.tsx</span>
                <span class="file-description">Runs in the browser</span>
              </div>

              <div class="code-block">
                ```typescript
                import { createClient } from "actor-core/client";
                import { createReactActorCore } from "@actor-core/react";
                import { useState, useEffect } from "react";
                import type { App } from "../actors/app";
                import type { Message } from "./actor";

                const client = createClient<App>("http://localhost:6420");
                const { useActor, useActorEvent } = createReactActorCore(client);

                export function AIAssistant() {
                  const [{ actor }] = useActor("aiAgent", { tags: { conversationId: "default" } });
                  const [messages, setMessages] = useState<Message[]>([]);
                  const [input, setInput] = useState("");
                  const [isLoading, setIsLoading] = useState(false);

                  // Load initial messages
                  useEffect(() => {
                    if (actor) {
                      actor.getMessages().then(setMessages);
                    }
                  }, [actor]);

                  // Listen for real-time messages
                  useActorEvent({ actor, event: "messageReceived" }, (message) => {
                    setMessages(prev => [...prev, message as Message]);
                    setIsLoading(false);
                  });

                  const handleSendMessage = async () => {
                    if (actor && input.trim()) {
                      setIsLoading(true);
                      
                      // Add user message to UI immediately
                      const userMessage = { role: "user", content: input } as Message;
                      setMessages(prev => [...prev, userMessage]);
                      
                      // Send to actor (AI response will come through the event)
                      await actor.sendMessage(input);
                      setInput("");
                    }
                  };

                  return (
                    <div className="ai-chat">
                      <div className="messages">
                        {messages.length === 0 ? (
                          <div className="empty-message">
                            Ask the AI assistant a question to get started
                          </div>
                        ) : (
                          messages.map((msg, i) => (
                            <div key={i} className={`message ${msg.role}`}>
                              <div className="avatar">
                                {msg.role === "user" ? "👤" : "🤖"}
                              </div>
                              <div className="content">{msg.content}</div>
                            </div>
                          ))
                        )}
                        {isLoading && (
                          <div className="message assistant loading">
                            <div className="avatar">🤖</div>
                            <div className="content">Thinking...</div>
                          </div>
                        )}
                      </div>
                      
                      <div className="input-area">
                        <input
                          value={input}
                          onChange={e => setInput(e.target.value)}
                          onKeyPress={e => e.key === "Enter" && handleSendMessage()}
                          placeholder="Ask the AI assistant..."
                          disabled={isLoading}
                        />
                        <button 
                          onClick={handleSendMessage}
                          disabled={isLoading || !input.trim()}
                        >
                          Send
                        </button>
                      </div>
                    </div>
                  );
                }
                ```
              </div>
            </div>
          </div>
        </div>

        <div class="code-panel" data-panel="ai-sqlite">
          <div class="code-split">
            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">actor.ts</span>
                <span class="file-description">Runs on the server</span>
              </div>

              <div class="code-block">
                ```typescript
                import { actor } from "actor-core";
                import { drizzle } from "@actor-core/drizzle";
                import { generateText, tool } from "ai";
                import { openai } from "@ai-sdk/openai";
                import { getWeather } from "./my-utils";
                import { messages } from "./schema";

                export type Message = { role: "user" | "assistant"; content: string; timestamp: number; }

                const aiAgent = actor({
                  sql: drizzle(),

                  actions: {
                    // Get conversation history
                    getMessages: async (c) => {
                      const result = await c.db
                        .select()
                        .from(messages)
                        .orderBy(messages.timestamp.asc());
                      
                      return result;
                    },

                    // Send a message to the AI and get a response
                    sendMessage: async (c, userMessage: string) => {
                      const now = Date.now();
                      
                      // Add user message to conversation
                      const userMsg = {
                        conversationId: c.actorId, // Use the actor instance ID
                        role: "user",
                        content: userMessage,
                      };
                      
                      // Store user message
                      await c.db
                        .insert(messages)
                        .values(userMsg);
                      
                      // Get all messages
                      const allMessages = await c.db
                        .select()
                        .from(messages)
                        .orderBy(messages.timestamp.asc());
                      
                      // Generate AI response using Vercel AI SDK with tools
                      const { text } = await generateText({
                        model: openai("o3-mini"),
                        prompt: userMessage,
                        messages: allMessages,
                        tools: {
                          weather: tool({
                            description: 'Get the weather in a location',
                            parameters: {
                              location: {
                                type: 'string',
                                description: 'The location to get the weather for',
                              },
                            },
                            execute: async ({ location }) => {
                              return await getWeather(location);
                            },
                          }),
                        },
                      });
                      
                      // Add AI response to conversation
                      const assistantMsg = {
                        role: "assistant",
                        content: text,
                      };
                      
                      // Store assistant message
                      await c.db
                        .insert(messages)
                        .values(assistantMsg);
                      
                      // Broadcast the new message to all connected clients
                      c.broadcast("messageReceived", assistantMsg);
                      
                      return assistantMsg;
                    },
                  }
                });

                export default aiAgent;
                ```
              </div>
            </div>

            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">App.tsx</span>
                <span class="file-description">Runs in the browser</span>
              </div>

              <div class="code-block">
                ```typescript
                import { createClient } from "actor-core/client";
                import { createReactActorCore } from "@actor-core/react";
                import { useState, useEffect } from "react";
                import type { App } from "../actors/app";
                import type { Message } from "./actor";

                const client = createClient<App>("http://localhost:6420");
                const { useActor, useActorEvent } = createReactActorCore(client);

                export function AIAssistant() {
                  const [{ actor }] = useActor("aiAgent", { tags: { conversationId: "default" } });
                  const [messages, setMessages] = useState<Message[]>([]);
                  const [input, setInput] = useState("");
                  const [isLoading, setIsLoading] = useState(false);

                  // Load initial messages
                  useEffect(() => {
                    if (actor) {
                      actor.getMessages().then(setMessages);
                    }
                  }, [actor]);

                  // Listen for real-time messages
                  useActorEvent({ actor, event: "messageReceived" }, (message) => {
                    setMessages(prev => [...prev, message as Message]);
                    setIsLoading(false);
                  });

                  const handleSendMessage = async () => {
                    if (actor && input.trim()) {
                      setIsLoading(true);
                      
                      // Add user message to UI immediately
                      const userMessage = { role: "user", content: input } as Message;
                      setMessages(prev => [...prev, userMessage]);
                      
                      // Send to actor (AI response will come through the event)
                      await actor.sendMessage(input);
                      setInput("");
                    }
                  };

                  return (
                    <div className="ai-chat">
                      <div className="messages">
                        {messages.length === 0 ? (
                          <div className="empty-message">
                            Ask the AI assistant a question to get started
                          </div>
                        ) : (
                          messages.map((msg, i) => (
                            <div key={i} className={`message ${msg.role}`}>
                              <div className="avatar">
                                {msg.role === "user" ? "👤" : "🤖"}
                              </div>
                              <div className="content">{msg.content}</div>
                            </div>
                          ))
                        )}
                        {isLoading && (
                          <div className="message assistant loading">
                            <div className="avatar">🤖</div>
                            <div className="content">Thinking...</div>
                          </div>
                        )}
                      </div>
                      
                      <div className="input-area">
                        <input
                          value={input}
                          onChange={e => setInput(e.target.value)}
                          onKeyPress={e => e.key === "Enter" && handleSendMessage()}
                          placeholder="Ask the AI assistant..."
                          disabled={isLoading}
                        />
                        <button 
                          onClick={handleSendMessage}
                          disabled={isLoading || !input.trim()}
                        >
                          Send
                        </button>
                      </div>
                    </div>
                  );
                }
                ```
              </div>
            </div>
          </div>
        </div>

        {/* Local-First Sync */}

        <div class="code-panel" data-panel="sync-memory">
          <div class="code-split">
            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">actor.ts</span>
                <span class="file-description">Runs on the server</span>
              </div>

              <div class="code-block">
                ```typescript
                import { actor } from "actor-core";

                export type Contact = { id: string; name: string; email: string; phone: string; updatedAt: number; }

                const contacts = actor({
                  // State is automatically persisted
                  state: {
                    contacts: {}
                  },
                  
                  actions: {
                    // Gets changes after the last timestamp (when coming back online)
                    getChanges: (c, after: number = 0) => {
                      const changes = Object.values(c.state.contacts)
                        .filter(contact => contact.updatedAt > after);
                      
                      return { 
                        changes,
                        timestamp: Date.now()
                      };
                    },
                    
                    // Pushes new changes from the client & handles conflicts
                    pushChanges: (c, contacts: Contact[]) => {
                      let changed = false;
                      
                      contacts.forEach(contact => {
                        const existing = c.state.contacts[contact.id];
                        
                        if (!existing || existing.updatedAt < contact.updatedAt) {
                          c.state.contacts[contact.id] = contact;
                          changed = true;
                        }
                      });
                      
                      if (changed) {
                        c.broadcast("contactsChanged", { 
                          contacts: Object.values(c.state.contacts)
                        });
                      }
                      
                      return { timestamp: Date.now() };
                    }
                  }
                });

                export default contacts;
                ```
              </div>
            </div>

            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">App.tsx</span>
                <span class="file-description">Runs in the browser</span>
              </div>

              <div class="code-block">
                ```tsx
                import { createClient } from "actor-core/client";
                import { createReactActorCore } from "@actor-core/react";
                import { useState, useEffect, useRef } from "react";
                import type { Contact } from "./actor";

                const client = createClient("http://localhost:6420");
                const { useActor, useActorEvent } = createReactActorCore(client);

                export function ContactsApp() {
                  const { actor } = useActor("contacts");
                  const [contacts, setContacts] = useState<Contact[]>([]);
                  const [name, setName] = useState("");
                  const [email, setEmail] = useState("");
                  const [phone, setPhone] = useState("");
                  const [syncStatus, setSyncStatus] = useState("Idle");
                  
                  const lastSyncTime = useRef(0);
                  
                  // Load initial contacts
                  useEffect(() => {
                    if (!actor) return;
                    
                    actor.getChanges(0).then(data => {
                      setContacts(data.changes);
                      lastSyncTime.current = data.timestamp;
                      setSyncStatus("Synced");
                    });
                  }, [actor]);
                  
                  // Handle contact events
                  useActorEvent({ actor, event: "contactsChanged" }, ({ contacts: updatedContacts }) => {
                    setContacts(prev => {
                      const contactMap = new Map(prev.map(c => [c.id, c]));
                      
                      updatedContacts.forEach(contact => {
                        const existing = contactMap.get(contact.id);
                        if (!existing || existing.updatedAt < contact.updatedAt) {
                          contactMap.set(contact.id, contact);
                        }
                      });
                      
                      return Array.from(contactMap.values());
                    });
                  });
                  
                  // Sync periodically
                  useEffect(() => {
                    if (!actor) return;
                    
                    const sync = async () => {
                      setSyncStatus("Syncing...");
                      
                      try {
                        // Get remote changes
                        const changes = await actor.getChanges(lastSyncTime.current);
                        
                        // Apply remote changes
                        if (changes.changes.length > 0) {
                          setContacts(prev => {
                            const contactMap = new Map(prev.map(c => [c.id, c]));
                            
                            changes.changes.forEach(contact => {
                              const existing = contactMap.get(contact.id);
                              if (!existing || existing.updatedAt < contact.updatedAt) {
                                contactMap.set(contact.id, contact);
                              }
                            });
                            
                            return Array.from(contactMap.values());
                          });
                        }
                        
                        // Push local changes
                        const localChanges = contacts.filter(c => c.updatedAt > lastSyncTime.current);
                        if (localChanges.length > 0) {
                          await actor.pushChanges(localChanges);
                        }
                        
                        lastSyncTime.current = changes.timestamp;
                        setSyncStatus("Synced");
                      } catch (error) {
                        setSyncStatus("Offline");
                      }
                    };
                    
                    const intervalId = setInterval(sync, 5000);
                    
                    return () => clearInterval(intervalId);
                  }, [actor, contacts]);
                  
                  // Add new contact (local first)
                  const addContact = () => {
                    if (!name.trim()) return;
                    
                    const newContact: Contact = {
                      id: Date.now().toString(),
                      name,
                      email,
                      phone,
                      updatedAt: Date.now()
                    };
                    
                    setContacts(prev => [...prev, newContact]);
                    
                    if (actor) {
                      actor.pushChanges([newContact]);
                    }
                    
                    setName("");
                    setEmail("");
                    setPhone("");
                  };
                  
                  // Delete contact (implemented as update with empty name)
                  const deleteContact = (id: string) => {
                    setContacts(prev => {
                      const updatedContacts = prev.map(c => 
                        c.id === id 
                          ? { ...c, name: "", updatedAt: Date.now() } 
                          : c
                      );
                      
                      if (actor) {
                        const deleted = updatedContacts.find(c => c.id === id);
                        if (deleted) {
                          actor.pushChanges([deleted]);
                        }
                      }
                      
                      return updatedContacts.filter(c => c.name !== "");
                    });
                  };
                  
                  // Manual sync
                  const handleSync = async () => {
                    if (!actor) return;
                    
                    setSyncStatus("Syncing...");
                    
                    try {
                      // Push all contacts
                      await actor.pushChanges(contacts);
                      
                      // Get all changes
                      const changes = await actor.getChanges(0);
                      
                      setContacts(changes.changes);
                      lastSyncTime.current = changes.timestamp;
                      setSyncStatus("Synced");
                    } catch (error) {
                      setSyncStatus("Offline");
                    }
                  };
                  
                  return (
                    <div className="contacts-app">
                      <div className="contacts-header">
                        <h2>Contacts</h2>
                        <div className="sync-status">
                          <span>{syncStatus}</span>
                          <button onClick={handleSync}>
                            Sync Now
                          </button>
                        </div>
                      </div>
                      
                      <div className="add-contact">
                        <input
                          type="text"
                          placeholder="Name"
                          value={name}
                          onChange={e => setName(e.target.value)}
                        />
                        <input
                          type="email"
                          placeholder="Email"
                          value={email}
                          onChange={e => setEmail(e.target.value)}
                        />
                        <input
                          type="tel"
                          placeholder="Phone"
                          value={phone}
                          onChange={e => setPhone(e.target.value)}
                        />
                        <button onClick={addContact}>Add Contact</button>
                      </div>
                      
                      <div className="contacts-list">
                        {contacts.filter(c => c.name !== "").map(contact => (
                          <div key={contact.id} className="contact-item">
                            <div className="contact-info">
                              <div className="contact-name">{contact.name}</div>
                              <div className="contact-details">
                                <div>{contact.email}</div>
                                <div>{contact.phone}</div>
                              </div>
                            </div>
                            <button 
                              className="delete-button"
                              onClick={() => deleteContact(contact.id)}
                            >
                              Delete
                            </button>
                          </div>
                        ))}
                      </div>
                    </div>
                  );
                }
                ```
              </div>
            </div>
          </div>
        </div>

        <div class="code-panel" data-panel="sync-sqlite">
          <div class="code-split">
            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">actor.ts</span>
                <span class="file-description">Runs on the server</span>
              </div>

              <div class="code-block">
                ```typescript
                import { actor } from "actor-core";
                import { drizzle } from "@actor-core/drizzle";
                import { contacts } from "./schema";

                export type Contact = { id: string; name: string; email: string; phone: string; updatedAt: number; }

                const contactSync = actor({
                  sql: drizzle(),
                  
                  actions: {
                    // Gets changes after the last timestamp (when coming back online)
                    getChanges: async (c, after: number = 0) => {
                      const changes = await c.db
                        .select()
                        .from(contacts)
                        .where(contacts.updatedAt.gt(after));
                      
                      return { 
                        changes,
                        timestamp: Date.now()
                      };
                    },
                    
                    // Pushes new changes from the client & handles conflicts
                    pushChanges: async (c, contactList: Contact[]) => {
                      let changed = false;
                      
                      for (const contact of contactList) {
                        // Check if contact exists with a newer timestamp
                        const existing = await c.db
                          .select()
                          .from(contacts)
                          .where(contacts.id.equals(contact.id))
                          .get();
                        
                        if (!existing || existing.updatedAt < contact.updatedAt) {
                          // Insert or update the contact
                          await c.db
                            .insert(contacts)
                            .values(contact)
                            .onConflictDoUpdate({
                              target: contacts.id,
                              set: contact
                            });
                          
                          changed = true;
                        }
                      }
                      
                      if (changed) {
                        // Get all contacts to broadcast
                        const allContacts = await c.db
                          .select()
                          .from(contacts);
                        
                        c.broadcast("contactsChanged", { 
                          contacts: allContacts
                        });
                      }
                      
                      return { timestamp: Date.now() };
                    }
                  }
                });

                export default contactSync;
                ```
              </div>
            </div>

            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">App.tsx</span>
                <span class="file-description">Runs in the browser</span>
              </div>

              <div class="code-block">
                ```tsx
                import { createClient } from "actor-core/client";
                import { createReactActorCore } from "@actor-core/react";
                import { useState, useEffect, useRef } from "react";
                import type { Contact } from "./actor";

                const client = createClient("http://localhost:6420");
                const { useActor, useActorEvent } = createReactActorCore(client);

                export function ContactsApp() {
                  const { actor } = useActor("contacts");
                  const [contacts, setContacts] = useState<Contact[]>([]);
                  const [name, setName] = useState("");
                  const [email, setEmail] = useState("");
                  const [phone, setPhone] = useState("");
                  const [syncStatus, setSyncStatus] = useState("Idle");
                  
                  const lastSyncTime = useRef(0);
                  
                  // Load initial contacts
                  useEffect(() => {
                    if (!actor) return;
                    
                    actor.getChanges(0).then(data => {
                      setContacts(data.changes);
                      lastSyncTime.current = data.timestamp;
                      setSyncStatus("Synced");
                    });
                  }, [actor]);
                  
                  // Handle contact events
                  useActorEvent({ actor, event: "contactsChanged" }, ({ contacts: updatedContacts }) => {
                    setContacts(prev => {
                      const contactMap = new Map(prev.map(c => [c.id, c]));
                      
                      updatedContacts.forEach(contact => {
                        const existing = contactMap.get(contact.id);
                        if (!existing || existing.updatedAt < contact.updatedAt) {
                          contactMap.set(contact.id, contact);
                        }
                      });
                      
                      return Array.from(contactMap.values());
                    });
                  });
                  
                  // Sync periodically
                  useEffect(() => {
                    if (!actor) return;
                    
                    const sync = async () => {
                      setSyncStatus("Syncing...");
                      
                      try {
                        // Get remote changes
                        const changes = await actor.getChanges(lastSyncTime.current);
                        
                        // Apply remote changes
                        if (changes.changes.length > 0) {
                          setContacts(prev => {
                            const contactMap = new Map(prev.map(c => [c.id, c]));
                            
                            changes.changes.forEach(contact => {
                              const existing = contactMap.get(contact.id);
                              if (!existing || existing.updatedAt < contact.updatedAt) {
                                contactMap.set(contact.id, contact);
                              }
                            });
                            
                            return Array.from(contactMap.values());
                          });
                        }
                        
                        // Push local changes
                        const localChanges = contacts.filter(c => c.updatedAt > lastSyncTime.current);
                        if (localChanges.length > 0) {
                          await actor.pushChanges(localChanges);
                        }
                        
                        lastSyncTime.current = changes.timestamp;
                        setSyncStatus("Synced");
                      } catch (error) {
                        setSyncStatus("Offline");
                      }
                    };
                    
                    const intervalId = setInterval(sync, 5000);
                    
                    return () => clearInterval(intervalId);
                  }, [actor, contacts]);
                  
                  // Add new contact (local first)
                  const addContact = () => {
                    if (!name.trim()) return;
                    
                    const newContact: Contact = {
                      id: Date.now().toString(),
                      name,
                      email,
                      phone,
                      updatedAt: Date.now()
                    };
                    
                    setContacts(prev => [...prev, newContact]);
                    
                    if (actor) {
                      actor.pushChanges([newContact]);
                    }
                    
                    setName("");
                    setEmail("");
                    setPhone("");
                  };
                  
                  // Delete contact (implemented as update with empty name)
                  const deleteContact = (id: string) => {
                    setContacts(prev => {
                      const updatedContacts = prev.map(c => 
                        c.id === id 
                          ? { ...c, name: "", updatedAt: Date.now() } 
                          : c
                      );
                      
                      if (actor) {
                        const deleted = updatedContacts.find(c => c.id === id);
                        if (deleted) {
                          actor.pushChanges([deleted]);
                        }
                      }
                      
                      return updatedContacts.filter(c => c.name !== "");
                    });
                  };
                  
                  // Manual sync
                  const handleSync = async () => {
                    if (!actor) return;
                    
                    setSyncStatus("Syncing...");
                    
                    try {
                      // Push all contacts
                      await actor.pushChanges(contacts);
                      
                      // Get all changes
                      const changes = await actor.getChanges(0);
                      
                      setContacts(changes.changes);
                      lastSyncTime.current = changes.timestamp;
                      setSyncStatus("Synced");
                    } catch (error) {
                      setSyncStatus("Offline");
                    }
                  };
                  
                  return (
                    <div className="contacts-app">
                      <div className="contacts-header">
                        <h2>Contacts</h2>
                        <div className="sync-status">
                          <span>{syncStatus}</span>
                          <button onClick={handleSync}>
                            Sync Now
                          </button>
                        </div>
                      </div>
                      
                      <div className="add-contact">
                        <input
                          type="text"
                          placeholder="Name"
                          value={name}
                          onChange={e => setName(e.target.value)}
                        />
                        <input
                          type="email"
                          placeholder="Email"
                          value={email}
                          onChange={e => setEmail(e.target.value)}
                        />
                        <input
                          type="tel"
                          placeholder="Phone"
                          value={phone}
                          onChange={e => setPhone(e.target.value)}
                        />
                        <button onClick={addContact}>Add Contact</button>
                      </div>
                      
                      <div className="contacts-list">
                        {contacts.filter(c => c.name !== "").map(contact => (
                          <div key={contact.id} className="contact-item">
                            <div className="contact-info">
                              <div className="contact-name">{contact.name}</div>
                              <div className="contact-details">
                                <div>{contact.email}</div>
                                <div>{contact.phone}</div>
                              </div>
                            </div>
                            <button 
                              className="delete-button"
                              onClick={() => deleteContact(contact.id)}
                            >
                              Delete
                            </button>
                          </div>
                        ))}
                      </div>
                    </div>
                  );
                }
                ```
              </div>
            </div>
          </div>
        </div>

        {/* Per-Tenant SaaS */}

        <div class="code-panel" data-panel="tenant-memory">
          <div class="code-split">
            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">actor.ts</span>
                <span class="file-description">Runs on the server</span>
              </div>

              <div class="code-block">
                ```typescript
                import { actor } from "actor-core";
                import { authenticate } from "./my-utils";

                // Simple tenant organization actor
                const tenant = actor({
                  // Example initial state
                  state: {
                    members: [
                      { id: "user-1", name: "Alice", email: "alice@example.com", role: "admin" },
                      { id: "user-2", name: "Bob", email: "bob@example.com", role: "member" }
                    ],
                    invoices: [
                      { id: "inv-1", amount: 100, date: Date.now(), paid: true },
                      { id: "inv-2", amount: 200, date: Date.now(), paid: false }
                    ]
                  },

                  // Authentication
                  createConnState: async (c, { params }) => {
                    const token = params.token;
                    const userId = await authenticate(token);
                    return { userId };
                  },

                  actions: {
                    // Get all members
                    getMembers: (c) => {
                      return c.state.members;
                    },

                    // Get all invoices (only admin can access)
                    getInvoices: (c) => {
                      // Find the user's role by their userId
                      const userId = c.conn.userId;
                      const user = c.state.members.find(m => m.id === userId);
                      
                      // Only allow admins to see invoices
                      if (!user || user.role !== "admin") {
                        throw new UserError("Permission denied: requires admin role");
                      }
                      
                      return c.state.invoices;
                    }
                  }
                });

                export default tenant;
                ```
              </div>
            </div>

            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">App.tsx</span>
                <span class="file-description">Runs in the browser</span>
              </div>

              <div class="code-block">
                ```typescript
                import { createClient } from "actor-core/client";
                import { createReactActorCore } from "@actor-core/react";
                import { useState, useEffect } from "react";
                import type { App } from "../actors/app";

                // Create client and hooks
                const client = createClient<App>("http://localhost:6420");
                const { useActor } = createReactActorCore(client);

                export function OrgDashboard({ orgId }: { orgId: string }) {
                  // State for data
                  const [members, setMembers] = useState<any[]>([]);
                  const [invoices, setInvoices] = useState<any[]>([]);
                  const [error, setError] = useState("");

                  // Login as admin or regular user
                  const loginAsAdmin = () => {
                    setToken("auth:user-1"); // Alice is admin
                  };
                  
                  const loginAsMember = () => {
                    setToken("auth:user-2"); // Bob is member
                  };
                  
                  // Authentication token
                  const [token, setToken] = useState("");
                  
                  // Connect to tenant actor with authentication token
                  const [{ actor }] = useActor("tenant", { 
                    params: { token },
                    tags: { orgId }
                  });

                  // Load data when actor is available
                  useEffect(() => {
                    if (!actor || !token) return;
                    
                    const loadData = async () => {
                      try {
                        // Get members (available to all users)
                        const membersList = await actor.getMembers();
                        setMembers(membersList);
                        
                        // Try to get invoices (only available to admins)
                        try {
                          const invoicesList = await actor.getInvoices();
                          setInvoices(invoicesList);
                          setError("");
                        } catch (err: any) {
                          setError(err.message);
                        }
                      } catch (err) {
                        console.error("Failed to load data");
                      }
                    };
                    
                    loadData();
                  }, [actor, token]);

                  // Login screen when not authenticated
                  if (!token) {
                    return (
                      <div>
                        <h2>Organization Dashboard</h2>
                        <p>Choose a login:</p>
                        <button onClick={loginAsAdmin}>Login as Admin (Alice)</button>
                        <button onClick={loginAsMember}>Login as Member (Bob)</button>
                      </div>
                    );
                  }

                  return (
                    <div>
                      <h2>Organization Dashboard</h2>
                      <p>Logged in as: {token.split(":")[1]}</p>
                      
                      {/* Members Section - available to all users */}
                      <div>
                        <h3>Members</h3>
                        <table>
                          <thead>
                            <tr>
                              <th>Name</th>
                              <th>Email</th>
                              <th>Role</th>
                            </tr>
                          </thead>
                          <tbody>
                            {members.map(member => (
                              <tr key={member.id}>
                                <td>{member.name}</td>
                                <td>{member.email}</td>
                                <td>{member.role}</td>
                              </tr>
                            ))}
                          </tbody>
                        </table>
                      </div>
                      
                      {/* Invoices Section - only displayed to admins */}
                      <div>
                        <h3>Invoices</h3>
                        {error ? (
                          <div style={{ color: "red" }}>{error}</div>
                        ) : (
                          <table>
                            <thead>
                              <tr>
                                <th>Invoice #</th>
                                <th>Date</th>
                                <th>Amount</th>
                                <th>Status</th>
                              </tr>
                            </thead>
                            <tbody>
                              {invoices.map(invoice => (
                                <tr key={invoice.id}>
                                  <td>{invoice.id}</td>
                                  <td>{new Date(invoice.date).toLocaleDateString()}</td>
                                  <td>${invoice.amount}</td>
                                  <td>{invoice.paid ? "Paid" : "Unpaid"}</td>
                                </tr>
                              ))}
                            </tbody>
                          </table>
                        )}
                      </div>
                    </div>
                  );
                }
                ```
              </div>
            </div>
          </div>
        </div>

        <div class="code-panel" data-panel="tenant-sqlite">
          <div class="code-split">
            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">actor.ts</span>
                <span class="file-description">Runs on the server</span>
              </div>

              <div class="code-block">
                ```typescript
                import { actor } from "actor-core";
                import { drizzle } from "@actor-core/drizzle";
                import { members, invoices } from "./schema";
                import { authenticate } from "./my-utils";

                // Simple tenant organization actor
                const tenant = actor({
                  sql: drizzle(),

                  // Authentication
                  createConnState: async (c, { params }) => {
                    const token = params.token;
                    const userId = await authenticate(token);
                    return { userId };
                  },

                  actions: {
                    // Get all members
                    getMembers: async (c) => {
                      const result = await c.db
                        .select()
                        .from(members);
                      
                      return result;
                    },

                    // Get all invoices (only admin can access)
                    getInvoices: async (c) => {
                      // Find the user's role by their userId
                      const userId = c.conn.userId;
                      const user = await c.db
                        .select()
                        .from(members)
                        .where(members.id.equals(userId))
                        .get();
                      
                      // Only allow admins to see invoices
                      if (!user || user.role !== "admin") {
                        throw new Error("Permission denied: requires admin role");
                      }
                      
                      const result = await c.db
                        .select()
                        .from(invoices);
                      
                      return result;
                    }
                  }
                });

                export default tenant;
                ```
              </div>
            </div>

            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">App.tsx</span>
                <span class="file-description">Runs in the browser</span>
              </div>

              <div class="code-block">
                ```typescript
                import { createClient } from "actor-core/client";
                import { createReactActorCore } from "@actor-core/react";
                import { useState, useEffect } from "react";
                import type { App } from "../actors/app";

                // Create client and hooks
                const client = createClient<App>("http://localhost:6420");
                const { useActor } = createReactActorCore(client);

                export function OrgDashboard({ orgId }: { orgId: string }) {
                  // State for data
                  const [members, setMembers] = useState<any[]>([]);
                  const [invoices, setInvoices] = useState<any[]>([]);
                  const [error, setError] = useState("");

                  // Login as admin or regular user
                  const loginAsAdmin = () => {
                    setToken("auth:user-1"); // Alice is admin
                  };
                  
                  const loginAsMember = () => {
                    setToken("auth:user-2"); // Bob is member
                  };
                  
                  // Authentication token
                  const [token, setToken] = useState("");
                  
                  // Connect to tenant actor with authentication token
                  const [{ actor }] = useActor("tenant", { 
                    params: { token },
                    tags: { orgId }
                  });

                  // Load data when actor is available
                  useEffect(() => {
                    if (!actor || !token) return;
                    
                    const loadData = async () => {
                      try {
                        // Get members (available to all users)
                        const membersList = await actor.getMembers();
                        setMembers(membersList);
                        
                        // Try to get invoices (only available to admins)
                        try {
                          const invoicesList = await actor.getInvoices();
                          setInvoices(invoicesList);
                          setError("");
                        } catch (err: any) {
                          setError(err.message);
                        }
                      } catch (err) {
                        console.error("Failed to load data");
                      }
                    };
                    
                    loadData();
                  }, [actor, token]);

                  // Login screen when not authenticated
                  if (!token) {
                    return (
                      <div>
                        <h2>Organization Dashboard</h2>
                        <p>Choose a login:</p>
                        <button onClick={loginAsAdmin}>Login as Admin (Alice)</button>
                        <button onClick={loginAsMember}>Login as Member (Bob)</button>
                      </div>
                    );
                  }

                  return (
                    <div>
                      <h2>Organization Dashboard</h2>
                      <p>Logged in as: {token.split(":")[1]}</p>
                      
                      {/* Members Section - available to all users */}
                      <div>
                        <h3>Members</h3>
                        <table>
                          <thead>
                            <tr>
                              <th>Name</th>
                              <th>Email</th>
                              <th>Role</th>
                            </tr>
                          </thead>
                          <tbody>
                            {members.map(member => (
                              <tr key={member.id}>
                                <td>{member.name}</td>
                                <td>{member.email}</td>
                                <td>{member.role}</td>
                              </tr>
                            ))}
                          </tbody>
                        </table>
                      </div>
                      
                      {/* Invoices Section - only displayed to admins */}
                      <div>
                        <h3>Invoices</h3>
                        {error ? (
                          <div style={{ color: "red" }}>{error}</div>
                        ) : (
                          <table>
                            <thead>
                              <tr>
                                <th>Invoice #</th>
                                <th>Date</th>
                                <th>Amount</th>
                                <th>Status</th>
                              </tr>
                            </thead>
                            <tbody>
                              {invoices.map(invoice => (
                                <tr key={invoice.id}>
                                  <td>{invoice.id}</td>
                                  <td>{new Date(invoice.date).toLocaleDateString()}</td>
                                  <td>${invoice.amount}</td>
                                  <td>{invoice.paid ? "Paid" : "Unpaid"}</td>
                                </tr>
                              ))}
                            </tbody>
                          </table>
                        )}
                      </div>
                    </div>
                  );
                }
                ```
              </div>
            </div>
          </div>
        </div>

        {/* Per-User Databases */}

        <div class="code-panel" data-panel="database-memory">
          <div class="code-split">
            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">actor.ts</span>
                <span class="file-description">Runs on the server</span>
              </div>

              <div class="code-block">
                ```typescript
                import { actor } from "actor-core";
                import { authenticate } from "./my-utils";

                export type Note = { id: string; content: string; updatedAt: number };

                // User notes actor
                const notes = actor({
                  state: {
                    notes: [] as Note[]
                  },
                  
                  // Authenticate
                  createConnState: async (c, { params }) => {
                    const token = params.token;
                	const userId = await authenticate(token);
                    return { userId };
                  },

                  actions: {
                    // Get all notes
                    getNotes: (c) => c.state.notes,

                    // Update note or create if it doesn't exist
                    updateNote: (c, { id, content }) => {
                      const noteIndex = c.state.notes.findIndex(note => note.id === id);
                      let note;
                      
                      if (noteIndex >= 0) {
                        // Update existing note
                        note = c.state.notes[noteIndex];
                        note.content = content;
                        note.updatedAt = Date.now();
                        c.broadcast("noteUpdated", note);
                      } else {
                        // Create new note
                        note = {
                          id: id || `note-${Date.now()}`,
                          content,
                          updatedAt: Date.now()
                        };
                        c.state.notes.push(note);
                        c.broadcast("noteAdded", note);
                      }
                      
                      return note;
                    },

                    // Delete note
                    deleteNote: (c, { id }) => {
                      const noteIndex = c.state.notes.findIndex(note => note.id === id);
                      if (noteIndex >= 0) {
                        c.state.notes.splice(noteIndex, 1);
                        c.broadcast("noteDeleted", { id });
                      }
                    }
                  }
                });

                export default notes;
                ```
              </div>
            </div>

            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">App.tsx</span>
                <span class="file-description">Runs in the browser</span>
              </div>

              <div class="code-block">
                ```typescript
                import { createClient } from "actor-core/client";
                import { createReactActorCore } from "@actor-core/react";
                import { useState, useEffect } from "react";

                const client = createClient("http://localhost:6420");
                const { useActor, useActorEvent } = createReactActorCore(client);

                export function NotesApp({ userId }: { userId: string }) {
                  const [notes, setNotes] = useState<Array<{ id: string, content: string }>>([]);
                  const [newNote, setNewNote] = useState("");
                  
                  // Connect to actor with auth token
                  const [{ actor }] = useActor("notes", { 
                    params: { userId, token: "demo-token" }
                  });
                  
                  // Load initial notes
                  useEffect(() => {
                    if (actor) {
                      actor.getNotes().then(setNotes);
                    }
                  }, [actor]);
                  
                  // Add a new note
                  const addNote = async () => {
                    if (actor && newNote.trim()) {
                      await actor.updateNote({ id: `note-${Date.now()}`, content: newNote });
                      setNewNote("");
                    }
                  };
                  
                  // Delete a note
                  const deleteNote = (id: string) => {
                    if (actor) {
                      actor.deleteNote({ id });
                    }
                  };
                  
                  // Listen for realtime updates
                  useActorEvent({ actor, event: "noteAdded" }, (note) => {
                    setNotes(notes => [...notes, note]);
                  });
                  
                  useActorEvent({ actor, event: "noteUpdated" }, (updatedNote) => {
                    setNotes(notes => notes.map(note => 
                      note.id === updatedNote.id ? updatedNote : note
                    ));
                  });
                  
                  useActorEvent({ actor, event: "noteDeleted" }, ({ id }) => {
                    setNotes(notes => notes.filter(note => note.id !== id));
                  });
                  
                  return (
                    <div>
                      <h2>My Notes</h2>
                      
                      <div>
                        <input 
                          value={newNote}
                          onChange={e => setNewNote(e.target.value)}
                          placeholder="Enter a new note"
                        />
                        <button onClick={addNote}>Add</button>
                      </div>
                      
                      <ul>
                        {notes.map(note => (
                          <li key={note.id}>
                            {note.content}
                            <button onClick={() => deleteNote(note.id)}>Delete</button>
                          </li>
                        ))}
                      </ul>
                    </div>
                  );
                }
                ```
              </div>
            </div>
          </div>
        </div>

        <div class="code-panel" data-panel="database-sqlite">
          <div class="code-split">
            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">actor.ts</span>
                <span class="file-description">Runs on the server</span>
              </div>

              <div class="code-block">
                ```typescript
                import { actor } from "actor-core";
                import { drizzle } from "@actor-core/drizzle";
                import { notes } from "./schema";
                import { authenticate } from "./my-utils";

                export type Note = { id: string; content: string; updatedAt: number };

                // User notes actor
                const userNotes = actor({
                  sql: drizzle(),
                  
                  // Authenticate
                  createConnState: async (c, { params }) => {
                    const token = params.token;
                    const userId = await authenticate(token);
                    return { userId };
                  },

                  actions: {
                    // Get all notes
                    getNotes: async (c) => {
                      const result = await c.db
                        .select()
                        .from(notes);
                      
                      return result;
                    },

                    // Update note or create if it doesn't exist
                    updateNote: async (c, { id, content }) => {
                      // Ensure the note ID exists or create a new one
                      const noteId = id || `note-${Date.now()}`;
                      
                      // Check if note exists
                      const existingNote = await c.db
                        .select()
                        .from(notes)
                        .where(notes.id.equals(noteId))
                        .get();
                      
                      if (existingNote) {
                        // Update existing note
                        await c.db
                          .update(notes)
                          .set({
                            content
                          })
                          .where(notes.id.equals(noteId));
                        
                        const updatedNote = {
                          id: noteId,
                          content
                        };
                        
                        c.broadcast("noteUpdated", updatedNote);
                        return updatedNote;
                      } else {
                        // Create new note
                        const newNote = {
                          id: noteId,
                          content
                        };
                        
                        await c.db
                          .insert(notes)
                          .values(newNote);
                        
                        c.broadcast("noteAdded", newNote);
                        return newNote;
                      }
                    },

                    // Delete note
                    deleteNote: async (c, { id }) => {
                      // Delete the note
                      await c.db
                        .delete(notes)
                        .where(notes.id.equals(id));
                      
                      c.broadcast("noteDeleted", { id });
                    }
                  }
                });

                export default userNotes;
                ```
              </div>
            </div>

            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">App.tsx</span>
                <span class="file-description">Runs in the browser</span>
              </div>

              <div class="code-block">
                ```typescript
                import { createClient } from "actor-core/client";
                import { createReactActorCore } from "@actor-core/react";
                import { useState, useEffect } from "react";

                const client = createClient("http://localhost:6420");
                const { useActor, useActorEvent } = createReactActorCore(client);

                export function NotesApp({ userId }: { userId: string }) {
                  const [notes, setNotes] = useState<Array<{ id: string, content: string }>>([]);
                  const [newNote, setNewNote] = useState("");
                  
                  // Connect to actor with auth token
                  const [{ actor }] = useActor("notes", { 
                    params: { userId, token: "demo-token" }
                  });
                  
                  // Load initial notes
                  useEffect(() => {
                    if (actor) {
                      actor.getNotes().then(setNotes);
                    }
                  }, [actor]);
                  
                  // Add a new note
                  const addNote = async () => {
                    if (actor && newNote.trim()) {
                      await actor.updateNote({ id: `note-${Date.now()}`, content: newNote });
                      setNewNote("");
                    }
                  };
                  
                  // Delete a note
                  const deleteNote = (id: string) => {
                    if (actor) {
                      actor.deleteNote({ id });
                    }
                  };
                  
                  // Listen for realtime updates
                  useActorEvent({ actor, event: "noteAdded" }, (note) => {
                    setNotes(notes => [...notes, note]);
                  });
                  
                  useActorEvent({ actor, event: "noteUpdated" }, (updatedNote) => {
                    setNotes(notes => notes.map(note => 
                      note.id === updatedNote.id ? updatedNote : note
                    ));
                  });
                  
                  useActorEvent({ actor, event: "noteDeleted" }, ({ id }) => {
                    setNotes(notes => notes.filter(note => note.id !== id));
                  });
                  
                  return (
                    <div>
                      <h2>My Notes</h2>
                      
                      <div>
                        <input 
                          value={newNote}
                          onChange={e => setNewNote(e.target.value)}
                          placeholder="Enter a new note"
                        />
                        <button onClick={addNote}>Add</button>
                      </div>
                      
                      <ul>
                        {notes.map(note => (
                          <li key={note.id}>
                            {note.content}
                            <button onClick={() => deleteNote(note.id)}>Delete</button>
                          </li>
                        ))}
                      </ul>
                    </div>
                  );
                }
                ```
              </div>
            </div>
          </div>
        </div>

        {/* Yjs CRDT */}

        <div class="code-panel" data-panel="crdt-memory">
          <div class="code-split">
            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">actor.ts</span>
                <span class="file-description">Runs on the server</span>
              </div>

              <div class="code-block">
                ```typescript
                import { actor } from "actor-core";
                import * as Y from 'yjs';
                import { encodeStateAsUpdate, applyUpdate } from 'yjs';

                const yjsDocument = actor({
                  // State: just the serialized Yjs document data
                  state: {
                    docData: "", // Base64 encoded Yjs document
                    lastModified: 0
                  },
                  
                  // In-memory Yjs objects (not serialized)
                  createVars: () => ({
                    doc: new Y.Doc()
                  }),
                  
                  // Initialize document from state when actor starts
                  onStart: (c) => {
                    if (c.state.docData) {
                      const binary = atob(c.state.docData);
                      const bytes = new Uint8Array(binary.length);
                      for (let i = 0; i < binary.length; i++) {
                        bytes[i] = binary.charCodeAt(i);
                      }
                      applyUpdate(c.vars.doc, bytes);
                    }
                  },
                  
                  // Handle client connections
                  onConnect: (c) => {
                    // Send initial document state to client
                    const update = encodeStateAsUpdate(c.vars.doc);
                    const base64 = bufferToBase64(update);
                    
                    c.conn.send("initialState", { update: base64 });
                  },


                  actions: {
                    // Apply a Yjs update from a client
                    applyUpdate: (c, updateBase64: string) => {
                      // Convert base64 to binary
                      const binary = atob(updateBase64);
                      const update = new Uint8Array(binary.length);
                      for (let i = 0; i < binary.length; i++) {
                        update[i] = binary.charCodeAt(i);
                      }
                      
                      // Apply update to Yjs document
                      applyUpdate(c.vars.doc, update);
                      
                      // Save document state
                      const fullState = encodeStateAsUpdate(c.vars.doc);
                      c.state.docData = bufferToBase64(fullState);
                      c.state.lastModified = Date.now();
                      
                      // Broadcast to all clients
                      c.broadcast("update", { update: updateBase64 });
                    }
                  }
                });

                // Helper to convert ArrayBuffer to base64
                function bufferToBase64(buffer: Uint8Array): string {
                  let binary = '';
                  for (let i = 0; i < buffer.byteLength; i++) {
                    binary += String.fromCharCode(buffer[i]);
                  }
                  return btoa(binary);
                }

                export default yjsDocument;
                ```
              </div>
            </div>

            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">App.tsx</span>
                <span class="file-description">Runs in the browser</span>
              </div>

              <div class="code-block">
                ```typescript
                import { createClient } from "actor-core/client";
                import { createReactActorCore } from "@actor-core/react";
                import { useState, useEffect, useRef } from "react";
                import * as Y from 'yjs';
                import { applyUpdate, encodeStateAsUpdate } from 'yjs';
                import type { App } from "../actors/app";

                const client = createClient<App>("http://localhost:6420");
                const { useActor, useActorEvent } = createReactActorCore(client);

                export function YjsEditor({ documentId = "shared-doc" }) {
                  // Connect to specific document using tags
                  const { actor } = useActor("yjsDocument", { 
                    tags: { documentId }
                  });
                  
                  // Document state
                  const [isLoading, setIsLoading] = useState(true);
                  const [text, setText] = useState("");
                  
                  // Local Yjs document
                  const yDocRef = useRef<Y.Doc | null>(null);
                  // Flag to prevent infinite update loops
                  const updatingFromServer = useRef(false);
                  const updatingFromLocal = useRef(false);
                  // Track if we've initialized observation
                  const observationInitialized = useRef(false);

                  // Initialize local Yjs document and connect
                  useEffect(() => {
                    // Create Yjs document
                    const yDoc = new Y.Doc();
                    yDocRef.current = yDoc;
                    setIsLoading(false);
                    
                    return () => {
                      // Clean up Yjs document
                      yDoc.destroy();
                    };
                  }, [actor]);
                  
                  // Set up text observation
                  useEffect(() => {
                    const yDoc = yDocRef.current;
                    if (!yDoc || observationInitialized.current) return;
                    
                    // Get the Yjs Text type from the document
                    const yText = yDoc.getText('content');
                    
                    // Observe changes to the text
                    yText.observe(() => {
                      // Only update UI if change wasn't from server
                      if (!updatingFromServer.current) {
                        // Update React state
                        setText(yText.toString());
                        
                        if (actor && !updatingFromLocal.current) {
                          // Set flag to prevent loops
                          updatingFromLocal.current = true;
                          
                          // Convert update to base64 and send to server
                          const update = encodeStateAsUpdate(yDoc);
                          const base64 = bufferToBase64(update);
                          actor.applyUpdate(base64).finally(() => {
                            updatingFromLocal.current = false;
                          });
                        }
                      }
                    });
                    
                    observationInitialized.current = true;
                  }, [actor]);

                  // Handle initial state from server
                  useActorEvent({ actor, event: "initialState" }, ({ update }) => {
                    const yDoc = yDocRef.current;
                    if (!yDoc) return;
                    
                    // Set flag to prevent update loops
                    updatingFromServer.current = true;
                    
                    try {
                      // Convert base64 to binary and apply to document
                      const binary = atob(update);
                      const bytes = new Uint8Array(binary.length);
                      for (let i = 0; i < binary.length; i++) {
                        bytes[i] = binary.charCodeAt(i);
                      }
                      
                      // Apply update to Yjs document
                      applyUpdate(yDoc, bytes);
                      
                      // Update React state
                      const yText = yDoc.getText('content');
                      setText(yText.toString());
                    } catch (error) {
                      console.error("Error applying initial update:", error);
                    } finally {
                      updatingFromServer.current = false;
                    }
                  });

                  // Handle updates from other clients
                  useActorEvent({ actor, event: "update" }, ({ update }) => {
                    const yDoc = yDocRef.current;
                    if (!yDoc) return;
                    
                    // Set flag to prevent update loops
                    updatingFromServer.current = true;
                    
                    try {
                      // Convert base64 to binary and apply to document
                      const binary = atob(update);
                      const bytes = new Uint8Array(binary.length);
                      for (let i = 0; i < binary.length; i++) {
                        bytes[i] = binary.charCodeAt(i);
                      }
                      
                      // Apply update to Yjs document
                      applyUpdate(yDoc, bytes);
                      
                      // Update React state
                      const yText = yDoc.getText('content');
                      setText(yText.toString());
                    } catch (error) {
                      console.error("Error applying update:", error);
                    } finally {
                      updatingFromServer.current = false;
                    }
                  });

                  // Handle text changes from user
                  const handleTextChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
                    if (!yDocRef.current) return;
                    
                    const newText = e.target.value;
                    const yText = yDocRef.current.getText('content');
                    
                    // Only update if text actually changed
                    if (newText !== yText.toString()) {
                      // Set flag to avoid loops
                      updatingFromLocal.current = true;
                      
                      // Update Yjs document (this will trigger observe callback)
                      yDocRef.current.transact(() => {
                        yText.delete(0, yText.length);
                        yText.insert(0, newText);
                      });
                      
                      updatingFromLocal.current = false;
                    }
                  };

                  if (isLoading) {
                    return <div className="loading">Loading collaborative document...</div>;
                  }

                  return (
                    <div className="yjs-editor">
                      <h3>Collaborative Document: {documentId}</h3>
                      <textarea
                        value={text}
                        onChange={handleTextChange}
                        placeholder="Start typing... All changes are synchronized in real-time!"
                        className="collaborative-textarea"
                      />
                    </div>
                  );
                }

                // Helper to convert ArrayBuffer to base64
                function bufferToBase64(buffer: Uint8Array): string {
                  let binary = '';
                  for (let i = 0; i < buffer.byteLength; i++) {
                    binary += String.fromCharCode(buffer[i]);
                  }
                  return btoa(binary);
                }
                ```
              </div>
            </div>
          </div>
        </div>

        <div class="code-panel" data-panel="crdt-sqlite">
          <div class="code-split">
            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">actor.ts</span>
                <span class="file-description">Runs on the server</span>
              </div>

              <div class="code-block">
                ```typescript
                import { actor } from "actor-core";
                import { drizzle } from "@actor-core/drizzle";
                import * as Y from 'yjs';
                import { encodeStateAsUpdate, applyUpdate } from 'yjs';
                import { documents } from "./schema";

                const yjsDocument = actor({
                  sql: drizzle(),
                  
                  // In-memory Yjs objects (not serialized)
                  createVars: () => ({
                    doc: new Y.Doc()
                  }),
                  
                  // Initialize document from state when actor starts
                  onStart: async (c) => {
                    // Get document data from database
                    const documentData = await c.db
                      .select()
                      .from(documents)
                      .get();
                      
                    if (documentData?.docData) {
                      try {
                        // Parse the docData from string to binary
                        const binary = atob(documentData.docData);
                        const bytes = new Uint8Array(binary.length);
                        for (let i = 0; i < binary.length; i++) {
                          bytes[i] = binary.charCodeAt(i);
                        }
                        applyUpdate(c.vars.doc, bytes);
                      } catch (error) {
                        console.error("Failed to load document", error);
                      }
                    }
                  },
                  
                  // Handle client connections
                  onConnect: (c) => {
                    // Send initial document state to client
                    const update = encodeStateAsUpdate(c.vars.doc);
                    const base64 = bufferToBase64(update);
                    
                    c.conn.send("initialState", { update: base64 });
                  },

                  actions: {
                    // Apply a Yjs update from a client
                    applyUpdate: async (c, updateBase64: string) => {
                      try {
                        // Convert base64 to binary
                        const binary = atob(updateBase64);
                        const update = new Uint8Array(binary.length);
                        for (let i = 0; i < binary.length; i++) {
                          update[i] = binary.charCodeAt(i);
                        }
                        
                        // Apply update to Yjs document
                        applyUpdate(c.vars.doc, update);
                        
                        // Save document state to database
                        const fullState = encodeStateAsUpdate(c.vars.doc);
                        const docData = bufferToBase64(fullState);
                        
                        // Store in database
                        await c.db
                          .insert(documents)
                          .values({
                            docData
                          })
                          .onConflictDoUpdate({
                            target: documents.id,
                            set: {
                              docData
                            }
                          });
                        
                        // Broadcast to all clients
                        c.broadcast("update", { update: updateBase64 });
                      } catch (error) {
                        console.error("Failed to apply update", error);
                      }
                    }
                  }
                });

                // Helper to convert ArrayBuffer to base64
                function bufferToBase64(buffer: Uint8Array): string {
                  let binary = '';
                  for (let i = 0; i < buffer.byteLength; i++) {
                    binary += String.fromCharCode(buffer[i]);
                  }
                  return btoa(binary);
                }

                export default yjsDocument;
                ```
              </div>
            </div>

            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">App.tsx</span>
                <span class="file-description">Runs in the browser</span>
              </div>

              <div class="code-block">
                ```typescript
                import { createClient } from "actor-core/client";
                import { createReactActorCore } from "@actor-core/react";
                import { useState, useEffect, useRef } from "react";
                import * as Y from 'yjs';
                import { applyUpdate, encodeStateAsUpdate } from 'yjs';
                import type { App } from "../actors/app";

                const client = createClient<App>("http://localhost:6420");
                const { useActor, useActorEvent } = createReactActorCore(client);

                export function YjsEditor({ documentId = "shared-doc" }) {
                  // Connect to specific document using tags
                  const { actor } = useActor("yjsDocument", { 
                    tags: { documentId }
                  });
                  
                  // Document state
                  const [isLoading, setIsLoading] = useState(true);
                  const [text, setText] = useState("");
                  
                  // Local Yjs document
                  const yDocRef = useRef<Y.Doc | null>(null);
                  // Flag to prevent infinite update loops
                  const updatingFromServer = useRef(false);
                  const updatingFromLocal = useRef(false);
                  // Track if we've initialized observation
                  const observationInitialized = useRef(false);

                  // Initialize local Yjs document and connect
                  useEffect(() => {
                    // Create Yjs document
                    const yDoc = new Y.Doc();
                    yDocRef.current = yDoc;
                    setIsLoading(false);
                    
                    return () => {
                      // Clean up Yjs document
                      yDoc.destroy();
                    };
                  }, [actor]);
                  
                  // Set up text observation
                  useEffect(() => {
                    const yDoc = yDocRef.current;
                    if (!yDoc || observationInitialized.current) return;
                    
                    // Get the Yjs Text type from the document
                    const yText = yDoc.getText('content');
                    
                    // Observe changes to the text
                    yText.observe(() => {
                      // Only update UI if change wasn't from server
                      if (!updatingFromServer.current) {
                        // Update React state
                        setText(yText.toString());
                        
                        if (actor && !updatingFromLocal.current) {
                          // Set flag to prevent loops
                          updatingFromLocal.current = true;
                          
                          // Convert update to base64 and send to server
                          const update = encodeStateAsUpdate(yDoc);
                          const base64 = bufferToBase64(update);
                          actor.applyUpdate(base64).finally(() => {
                            updatingFromLocal.current = false;
                          });
                        }
                      }
                    });
                    
                    observationInitialized.current = true;
                  }, [actor]);

                  // Handle initial state from server
                  useActorEvent({ actor, event: "initialState" }, ({ update }) => {
                    const yDoc = yDocRef.current;
                    if (!yDoc) return;
                    
                    // Set flag to prevent update loops
                    updatingFromServer.current = true;
                    
                    try {
                      // Convert base64 to binary and apply to document
                      const binary = atob(update);
                      const bytes = new Uint8Array(binary.length);
                      for (let i = 0; i < binary.length; i++) {
                        bytes[i] = binary.charCodeAt(i);
                      }
                      
                      // Apply update to Yjs document
                      applyUpdate(yDoc, bytes);
                      
                      // Update React state
                      const yText = yDoc.getText('content');
                      setText(yText.toString());
                    } catch (error) {
                      console.error("Error applying initial update:", error);
                    } finally {
                      updatingFromServer.current = false;
                    }
                  });

                  // Handle updates from other clients
                  useActorEvent({ actor, event: "update" }, ({ update }) => {
                    const yDoc = yDocRef.current;
                    if (!yDoc) return;
                    
                    // Set flag to prevent update loops
                    updatingFromServer.current = true;
                    
                    try {
                      // Convert base64 to binary and apply to document
                      const binary = atob(update);
                      const bytes = new Uint8Array(binary.length);
                      for (let i = 0; i < binary.length; i++) {
                        bytes[i] = binary.charCodeAt(i);
                      }
                      
                      // Apply update to Yjs document
                      applyUpdate(yDoc, bytes);
                      
                      // Update React state
                      const yText = yDoc.getText('content');
                      setText(yText.toString());
                    } catch (error) {
                      console.error("Error applying update:", error);
                    } finally {
                      updatingFromServer.current = false;
                    }
                  });

                  // Handle text changes from user
                  const handleTextChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
                    if (!yDocRef.current) return;
                    
                    const newText = e.target.value;
                    const yText = yDocRef.current.getText('content');
                    
                    // Only update if text actually changed
                    if (newText !== yText.toString()) {
                      // Set flag to avoid loops
                      updatingFromLocal.current = true;
                      
                      // Update Yjs document (this will trigger observe callback)
                      yDocRef.current.transact(() => {
                        yText.delete(0, yText.length);
                        yText.insert(0, newText);
                      });
                      
                      updatingFromLocal.current = false;
                    }
                  };

                  if (isLoading) {
                    return <div className="loading">Loading collaborative document...</div>;
                  }

                  return (
                    <div className="yjs-editor">
                      <h3>Collaborative Document: {documentId}</h3>
                      <textarea
                        value={text}
                        onChange={handleTextChange}
                        placeholder="Start typing... All changes are synchronized in real-time!"
                        className="collaborative-textarea"
                      />
                    </div>
                  );
                }

                // Helper to convert ArrayBuffer to base64
                function bufferToBase64(buffer: Uint8Array): string {
                  let binary = '';
                  for (let i = 0; i < buffer.byteLength; i++) {
                    binary += String.fromCharCode(buffer[i]);
                  }
                  return btoa(binary);
                }
                ```
              </div>
            </div>
          </div>
        </div>

        {/* Collaborative Document */}

        <div class="code-panel" data-panel="doc-memory">
          <div class="code-split">
            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">actor.ts</span>
                <span class="file-description">Runs on the server</span>
              </div>

              <div class="code-block">
                ```typescript
                import { actor } from "actor-core";

                export type Cursor = { x: number, y: number, userId: string };

                const document = actor({
                  state: {
                    text: "",
                    cursors: {} as Record<string, Cursor>,
                  },

                  actions: {
                    getText: (c) => c.state.text,

                    // Update the document (real use case has better conflict resolution)
                    setText: (c, text: string) => {
                      // Save document state
                      c.state.text = text;
                      
                      // Broadcast update
                      c.broadcast("textUpdated", {
                        text,
                        userId: c.conn.id
                      });
                    },

                    getCursors: (c) => c.state.cursors,
                    
                    updateCursor: (c, x: number, y: number) => {
                      // Update user location
                      const userId = c.conn.id;
                      c.state.cursors[userId] = { x, y, userId };
                      
                      // Broadcast location
                      c.broadcast("cursorUpdated", {
                        userId,
                        x, 
                        y
                      });
                    },
                  }
                });

                export default document;
                ```
              </div>
            </div>

            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">App.tsx</span>
                <span class="file-description">Runs in the browser</span>
              </div>

              <div class="code-block">
                ```typescript
                import { createClient } from "actor-core/client";
                import { createReactActorCore } from "@actor-core/react";
                import { useState, useEffect } from "react";
                import type { App } from "../actors/app";

                const client = createClient<App>("http://localhost:6420");
                const { useActor, useActorEvent } = createReactActorCore(client);

                export function DocumentEditor() {
                  // Connect to actor for this document ID from URL
                  const documentId = new URLSearchParams(window.location.search).get('id') || 'default-doc';
                  const [{ actor, connectionId }] = useActor("document", { tags: { id: documentId } });
                  
                  // Local state
                  const [text, setText] = useState("");
                  const [cursorPos, setCursorPos] = useState({ x: 0, y: 0 });
                  const [otherCursors, setOtherCursors] = useState({});
                  
                  // Load initial document state
                  useEffect(() => {
                    if (actor) {
                      actor.getText().then(setText);
                      actor.getCursors().then(setOtherCursors);
                    }
                  }, [actor]);
                  
                  // Listen for updates from other users
                  useActorEvent({ actor, event: "textUpdated" }, ({ text: newText, userId: senderId }) => {
                    if (senderId !== connectionId) setText(newText);
                  });
                  
                  useActorEvent({ actor, event: "cursorUpdated" }, ({ userId: cursorUserId, x, y }) => {
                    if (cursorUserId !== connectionId) {
                      setOtherCursors(prev => ({
                        ...prev,
                        [cursorUserId]: { x, y, userId: cursorUserId }
                      }));
                    }
                  });
                  
                  // Update cursor position
                  const updateCursor = (e) => {
                    if (!actor) return;
                    const rect = e.currentTarget.getBoundingClientRect();
                    const x = e.clientX - rect.left;
                    const y = e.clientY - rect.top;
                    
                    if (x !== cursorPos.x || y !== cursorPos.y) {
                      setCursorPos({ x, y });
                      actor.updateCursor(x, y);
                    }
                  };
                  
                  return (
                    <div className="document-editor">
                      <h2>Document: {documentId}</h2>
                      
                      <div onMouseMove={updateCursor}>
                        <textarea
                          value={text}
                          onChange={(e) => {
                            const newText = e.target.value;
                            setText(newText);
                            actor?.setText(newText);
                          }}
                          placeholder="Start typing..."
                        />
                        
                        {/* Other users' cursors */}
                        {Object.values(otherCursors).map((cursor: any) => (
                          <div 
                            key={cursor.userId}
                            style={{
                              position: 'absolute',
                              left: `${cursor.x}px`,
                              top: `${cursor.y}px`,
                              width: '10px',
                              height: '10px',
                              backgroundColor: 'red',
                              borderRadius: '50%'
                            }}
                          />
                        ))}
                      </div>
                      
                      <div>
                        <p>Connected users: You and {Object.keys(otherCursors).length} others</p>
                      </div>
                    </div>
                  );
                }
                ```
              </div>
            </div>
          </div>
        </div>

        <div class="code-panel" data-panel="doc-sqlite">
          <div class="code-split">
            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">actor.ts</span>
                <span class="file-description">Runs on the server</span>
              </div>

              <div class="code-block">
                ```typescript
                import { actor } from "actor-core";
                import { drizzle } from "@actor-core/drizzle";
                import { documents, cursors } from "./schema";

                export type Cursor = { x: number, y: number, userId: string };

                const document = actor({
                  sql: drizzle(),

                  actions: {
                    getText: async (c) => {
                      const doc = await c.db
                        .select()
                        .from(documents)
                        .get();
                      
                      return doc?.text || "";
                    },

                    // Update the document (real use case has better conflict resolution)
                    setText: async (c, text: string) => {
                      // Save document state
                      await c.db
                        .insert(documents)
                        .values({
                          text
                        })
                        .onConflictDoUpdate({
                          target: documents.id,
                          set: {
                            text
                          }
                        });
                      
                      // Broadcast update
                      c.broadcast("textUpdated", {
                        text,
                        userId: c.conn.id
                      });
                    },

                    getCursors: async (c) => {
                      const result = await c.db
                        .select()
                        .from(cursors);
                      
                      // Convert array to record object keyed by userId
                      return result.reduce((acc, cursor) => {
                        acc[cursor.userId] = {
                          x: cursor.x,
                          y: cursor.y,
                          userId: cursor.userId
                        };
                        return acc;
                      }, {} as Record<string, Cursor>);
                    },
                    
                    updateCursor: async (c, x: number, y: number) => {
                      // Update user location
                      const userId = c.conn.id;
                      
                      await c.db
                        .insert(cursors)
                        .values({
                          userId,
                          x,
                          y
                        })
                        .onConflictDoUpdate({
                          target: cursors.userId,
                          set: {
                            x,
                            y
                          }
                        });
                      
                      // Broadcast location
                      c.broadcast("cursorUpdated", {
                        userId,
                        x, 
                        y
                      });
                    },
                  }
                });

                export default document;
                ```
              </div>
            </div>

            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">App.tsx</span>
                <span class="file-description">Runs in the browser</span>
              </div>

              <div class="code-block">
                ```typescript
                import { createClient } from "actor-core/client";
                import { createReactActorCore } from "@actor-core/react";
                import { useState, useEffect } from "react";
                import type { App } from "../actors/app";

                const client = createClient<App>("http://localhost:6420");
                const { useActor, useActorEvent } = createReactActorCore(client);

                export function DocumentEditor() {
                  // Connect to actor for this document ID from URL
                  const documentId = new URLSearchParams(window.location.search).get('id') || 'default-doc';
                  const [{ actor, connectionId }] = useActor("document", { tags: { id: documentId } });
                  
                  // Local state
                  const [text, setText] = useState("");
                  const [cursorPos, setCursorPos] = useState({ x: 0, y: 0 });
                  const [otherCursors, setOtherCursors] = useState({});
                  
                  // Load initial document state
                  useEffect(() => {
                    if (actor) {
                      actor.getText().then(setText);
                      actor.getCursors().then(setOtherCursors);
                    }
                  }, [actor]);
                  
                  // Listen for updates from other users
                  useActorEvent({ actor, event: "textUpdated" }, ({ text: newText, userId: senderId }) => {
                    if (senderId !== connectionId) setText(newText);
                  });
                  
                  useActorEvent({ actor, event: "cursorUpdated" }, ({ userId: cursorUserId, x, y }) => {
                    if (cursorUserId !== connectionId) {
                      setOtherCursors(prev => ({
                        ...prev,
                        [cursorUserId]: { x, y, userId: cursorUserId }
                      }));
                    }
                  });
                  
                  // Update cursor position
                  const updateCursor = (e) => {
                    if (!actor) return;
                    const rect = e.currentTarget.getBoundingClientRect();
                    const x = e.clientX - rect.left;
                    const y = e.clientY - rect.top;
                    
                    if (x !== cursorPos.x || y !== cursorPos.y) {
                      setCursorPos({ x, y });
                      actor.updateCursor(x, y);
                    }
                  };
                  
                  return (
                    <div className="document-editor">
                      <h2>Document: {documentId}</h2>
                      
                      <div onMouseMove={updateCursor}>
                        <textarea
                          value={text}
                          onChange={(e) => {
                            const newText = e.target.value;
                            setText(newText);
                            actor?.setText(newText);
                          }}
                          placeholder="Start typing..."
                        />
                        
                        {/* Other users' cursors */}
                        {Object.values(otherCursors).map((cursor: any) => (
                          <div 
                            key={cursor.userId}
                            style={{
                              position: 'absolute',
                              left: `${cursor.x}px`,
                              top: `${cursor.y}px`,
                              width: '10px',
                              height: '10px',
                              backgroundColor: 'red',
                              borderRadius: '50%'
                            }}
                          />
                        ))}
                      </div>
                      
                      <div>
                        <p>Connected users: You and {Object.keys(otherCursors).length} others</p>
                      </div>
                    </div>
                  );
                }
                ```
              </div>
            </div>
          </div>
        </div>

        {/* Stream Processing */}

        <div class="code-panel" data-panel="stream-memory">
          <div class="code-split">
            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">actor.ts</span>
                <span class="file-description">Runs on the server</span>
              </div>

              <div class="code-block">
                ```typescript
                import { actor } from "actor-core";

                export type StreamState = {
                  topValues: number[];
                };

                // Simple top-K stream processor example
                const streamProcessor = actor({
                  state: {
                    topValues: [] as number[]
                  },

                  actions: {
                    getTopValues: (c) => c.state.topValues,

                    // Add value and keep top 3
                    addValue: (c, value: number) => {
                      // Insert new value if needed
                      const insertAt = c.state.topValues.findIndex(v => value > v);
                      if (insertAt === -1) {
                        c.state.topValues.push(value);
                      } else {
                        c.state.topValues.splice(insertAt, 0, value);
                      }
                      
                      // Keep only top 3
                      if (c.state.topValues.length > 3) {
                        c.state.topValues.length = 3;
                      }
                      
                      // Broadcast update to all clients
                      c.broadcast("updated", { topValues: c.state.topValues });
                      
                      return c.state.topValues;
                    },
                  }
                });

                export default streamProcessor;
                ```
              </div>
            </div>

            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">App.tsx</span>
                <span class="file-description">Runs in the browser</span>
              </div>

              <div class="code-block">
                ```typescript
                import { createClient } from "actor-core/client";
                import { createReactActorCore } from "@actor-core/react";
                import { useState, useEffect } from "react";
                import type { App } from "../actors/app";
                import type { StreamState } from "./actor"; // Import shared types from actor

                const client = createClient<App>("http://localhost:6420");
                const { useActor, useActorEvent } = createReactActorCore(client);

                export function StreamExample() {
                  const [{ actor }] = useActor("streamProcessor");
                  const [topValues, setTopValues] = useState<number[]>([]);
                  const [newValue, setNewValue] = useState<number>(0);

                  // Load initial values
                  useEffect(() => {
                    if (actor) {
                      actor.getTopValues().then(setTopValues);
                    }
                  }, [actor]);

                  // Listen for updates from other clients
                  useActorEvent({ actor, event: "updated" }, ({ topValues }) => {
                    setTopValues(topValues);
                  });

                  // Add a new value to the stream
                  const handleAddValue = () => {
                    if (actor) {
                      actor.addValue(newValue).then(setTopValues);
                      setNewValue(0);
                    }
                  };

                  return (
                    <div>
                      <h2>Top 3 Values</h2>
                      
                      <ul>
                        {topValues.map((value, i) => (
                          <li key={i}>{value}</li>
                        ))}
                      </ul>

                      <input
                        type="number"
                        value={newValue}
                        onChange={(e) => setNewValue(Number(e.target.value))}
                      />
                      <button onClick={handleAddValue}>Add Value</button>
                    </div>
                  );
                }
                ```
              </div>
            </div>
          </div>
        </div>

        <div class="code-panel" data-panel="stream-sqlite">
          <div class="code-split">
            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">actor.ts</span>
                <span class="file-description">Runs on the server</span>
              </div>

              <div class="code-block">
                ```typescript
                import { actor } from "actor-core";
                import { drizzle } from "@actor-core/drizzle";
                import { streams, streamValues } from "./schema";

                export type StreamState = { topValues: number[]; };

                // Simple top-K stream processor example
                const streamProcessor = actor({
                  sql: drizzle(),

                  actions: {
                    getTopValues: async (c) => {
                      // Get the top 3 values sorted in descending order
                      const result = await c.db
                        .select()
                        .from(streamValues)
                        .orderBy(streamValues.value.desc())
                        .limit(3);
                      
                      return result.map(r => r.value);
                    },

                    // Add value and keep top 3
                    addValue: async (c, value: number) => {
                      // Insert the new value
                      await c.db
                        .insert(streamValues)
                        .values({
                          value
                        });
                      
                      // Get the updated top 3 values
                      const topValues = await c.db
                        .select()
                        .from(streamValues)
                        .orderBy(streamValues.value.desc())
                        .limit(3);
                      
                      // Delete values that are no longer in the top 3
                      if (topValues.length === 3) {
                        await c.db
                          .delete(streamValues)
                          .where(streamValues.value.lt(topValues[2].value));
                      }
                      
                      const topValuesArray = topValues.map(r => r.value);
                      
                      // Broadcast update to all clients
                      c.broadcast("updated", { topValues: topValuesArray });
                      
                      return topValuesArray;
                    },
                  }
                });

                export default streamProcessor;
                ```
              </div>
            </div>

            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">App.tsx</span>
                <span class="file-description">Runs in the browser</span>
              </div>

              <div class="code-block">
                ```typescript
                import { createClient } from "actor-core/client";
                import { createReactActorCore } from "@actor-core/react";
                import { useState, useEffect } from "react";
                import type { App } from "../actors/app";
                import type { StreamState } from "./actor"; // Import shared types from actor

                const client = createClient<App>("http://localhost:6420");
                const { useActor, useActorEvent } = createReactActorCore(client);

                export function StreamExample() {
                  const [{ actor }] = useActor("streamProcessor");
                  const [topValues, setTopValues] = useState<number[]>([]);
                  const [newValue, setNewValue] = useState<number>(0);

                  // Load initial values
                  useEffect(() => {
                    if (actor) {
                      actor.getTopValues().then(setTopValues);
                    }
                  }, [actor]);

                  // Listen for updates from other clients
                  useActorEvent({ actor, event: "updated" }, ({ topValues }) => {
                    setTopValues(topValues);
                  });

                  // Add a new value to the stream
                  const handleAddValue = () => {
                    if (actor) {
                      actor.addValue(newValue).then(setTopValues);
                      setNewValue(0);
                    }
                  };

                  return (
                    <div>
                      <h2>Top 3 Values</h2>
                      
                      <ul>
                        {topValues.map((value, i) => (
                          <li key={i}>{value}</li>
                        ))}
                      </ul>

                      <input
                        type="number"
                        value={newValue}
                        onChange={(e) => setNewValue(Number(e.target.value))}
                      />
                      <button onClick={handleAddValue}>Add Value</button>
                    </div>
                  );
                }
                ```
              </div>
            </div>
          </div>
        </div>

        {/* Multiplayer Game */}

        <div class="code-panel" data-panel="game-memory">
          <div class="code-split">
            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">actor.ts</span>
                <span class="file-description">Runs on the server</span>
              </div>

              <div class="code-block">
                ```typescript
                import { actor } from "actor-core";

                export type Position = { x: number; y: number };
                export type Input = { x: number; y: number };
                export type Player = { id: string; position: Position; input: Input };

                const gameRoom = actor({
                  state: {
                    players: {} as Record<string, Player>,
                    mapSize: 800
                  },
                  
                  onStart: (c) => {
                    // Set up game update loop
                    setInterval(() => {
                      const worldUpdate = { playerList: [] };
                      
                      for (const id in c.state.players) {
                        const player = c.state.players[id];
                        const speed = 5;
                        
                        // Update position based on input
                        player.position.x += player.input.x * speed;
                        player.position.y += player.input.y * speed;
                        
                        // Keep player in bounds
                        player.position.x = Math.max(0, Math.min(player.position.x, c.state.mapSize));
                        player.position.y = Math.max(0, Math.min(player.position.y, c.state.mapSize));
                        
                        // Add to list for broadcast
                        worldUpdate.playerList.push(player);
                      }
                      
                      // Broadcast world state
                      c.broadcast("worldUpdate", worldUpdate);
                    }, 50);
                  },
                  
                  // Add player to game
                  onConnect: (c) => {
                    const id = c.conn.id;
                    c.state.players[id] = { 
                      id, 
                      position: {
                        x: Math.floor(Math.random() * c.state.mapSize),
                        y: Math.floor(Math.random() * c.state.mapSize)
                      },
                      input: { x: 0, y: 0 }
                    };
                  },
                  
                  // Remove player from game
                  onDisconnect: (c) => {
                    delete c.state.players[c.conn.id];
                  },
                  
                  actions: {
                    // Update movement
                    setInput: (c, input: Input) => {
                      const player = c.state.players[c.conn.id];
                      if (player) player.input = input;
                    }
                  }
                });

                export default gameRoom;
                ```
              </div>
            </div>

            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">App.tsx</span>
                <span class="file-description">Runs in the browser</span>
              </div>

              <div class="code-block">
                ```tsx
                import { createClient } from "actor-core/client";
                import { createReactActorCore } from "@actor-core/react";
                import { useState, useEffect, useRef } from "react";
                import type { Player } from "./actor";

                const client = createClient("http://localhost:6420");
                const { useActor, useActorEvent } = createReactActorCore(client);

                export function MultiplayerGame() {
                  const [{ actor, connectionId }] = useActor("gameRoom");
                  const [players, setPlayers] = useState<Player[]>([]);
                  const canvasRef = useRef<HTMLCanvasElement>(null);
                  const keysPressed = useRef<Record<string, boolean>>({});
                  
                  // Set up game
                  useEffect(() => {
                    if (!actor) return;
                    
                    // Set up keyboard handlers
                    const handleKeyDown = (e: KeyboardEvent) => {
                      keysPressed.current[e.key.toLowerCase()] = true;
                    };
                    
                    const handleKeyUp = (e: KeyboardEvent) => {
                      keysPressed.current[e.key.toLowerCase()] = false;
                    };
                    
                    window.addEventListener("keydown", handleKeyDown);
                    window.addEventListener("keyup", handleKeyUp);
                    
                    // Input update loop
                    const inputInterval = setInterval(() => {
                      const input = { x: 0, y: 0 };
                      
                      if (keysPressed.current["w"] || keysPressed.current["arrowup"]) input.y = -1;
                      if (keysPressed.current["s"] || keysPressed.current["arrowdown"]) input.y = 1;
                      if (keysPressed.current["a"] || keysPressed.current["arrowleft"]) input.x = -1;
                      if (keysPressed.current["d"] || keysPressed.current["arrowright"]) input.x = 1;
                      
                      actor.setInput(input);
                    }, 50);
                    
                    // Rendering loop
                    const renderLoop = () => {
                      const canvas = canvasRef.current;
                      if (!canvas) return;
                      
                      const ctx = canvas.getContext("2d");
                      if (!ctx) return;
                      
                      ctx.clearRect(0, 0, canvas.width, canvas.height);
                      
                      // Use for loop instead of forEach
                      for (let i = 0; i < players.length; i++) {
                        const player = players[i];
                        ctx.fillStyle = player.id === connectionId ? "blue" : "gray";
                        ctx.beginPath();
                        ctx.arc(player.position.x, player.position.y, 10, 0, Math.PI * 2);
                        ctx.fill();
                      }
                      
                      requestAnimationFrame(renderLoop);
                    };
                    
                    const animationId = requestAnimationFrame(renderLoop);
                    
                    return () => {
                      window.removeEventListener("keydown", handleKeyDown);
                      window.removeEventListener("keyup", handleKeyUp);
                      clearInterval(inputInterval);
                      cancelAnimationFrame(animationId);
                    };
                  }, [actor, connectionId, players]);
                  
                  // Listen for world updates
                  useActorEvent({ actor, event: "worldUpdate" }, ({ players: updatedPlayers }) => {
                    setPlayers(updatedPlayers);
                  });
                  
                  return (
                    <div>
                      <canvas 
                        ref={canvasRef} 
                        width={800} 
                        height={600} 
                        style={{ border: "1px solid black" }}
                      />
                      <p>Move: WASD or Arrow Keys</p>
                    </div>
                  );
                }
                ```
              </div>
            </div>
          </div>
        </div>

        <div class="code-panel" data-panel="game-sqlite">
          <div class="code-split">
            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">actor.ts</span>
                <span class="file-description">Runs on the server</span>
              </div>

              <div class="code-block">
                ```typescript
                import { actor } from "actor-core";
                import { drizzle } from "@actor-core/drizzle";
                import { players, gameSettings } from "./schema";

                export type Position = { x: number; y: number };
                export type Input = { x: number; y: number };
                export type Player = { id: string; position: Position; input: Input };

                const gameRoom = actor({
                  sql: drizzle(),
                  
                  // Store game settings and player inputs in memory for performance
                  createVars: () => ({
                    playerCache: {} as Record<string, Player>,
                    mapSize: 800
                  }),
                  
                  onStart: async (c) => {
                    // Get or initialize game settings
                    const settings = await c.db
                      .select()
                      .from(gameSettings)
                      .get();
                    
                    if (settings) {
                      c.vars.mapSize = settings.mapSize;
                    } else {
                      await c.db
                        .insert(gameSettings)
                        .values({
                          mapSize: c.vars.mapSize
                        });
                    }
                    
                    // Load existing players into memory
                    const existingPlayers = await c.db
                      .select()
                      .from(players);
                    
                    for (const player of existingPlayers) {
                      c.vars.playerCache[player.id] = {
                        id: player.id,
                        position: {
                          x: player.positionX,
                          y: player.positionY
                        },
                        input: {
                          x: player.inputX,
                          y: player.inputY
                        }
                      };
                    }
                    
                    // Set up game update loop
                    setInterval(async () => {
                      const worldUpdate = { playerList: [] };
                      let changed = false;
                      
                      for (const id in c.vars.playerCache) {
                        const player = c.vars.playerCache[id];
                        const speed = 5;
                        
                        // Update position based on input
                        player.position.x += player.input.x * speed;
                        player.position.y += player.input.y * speed;
                        
                        // Keep player in bounds
                        player.position.x = Math.max(0, Math.min(player.position.x, c.vars.mapSize));
                        player.position.y = Math.max(0, Math.min(player.position.y, c.vars.mapSize));
                        
                        // Add to list for broadcast
                        worldUpdate.playerList.push(player);
                        changed = true;
                      }
                      
                      // Save player positions to database if changed
                      if (changed) {
                        for (const id in c.vars.playerCache) {
                          const player = c.vars.playerCache[id];
                          
                          await c.db
                            .update(players)
                            .set({
                              positionX: player.position.x,
                              positionY: player.position.y
                            })
                            .where(players.id.equals(id));
                        }
                        
                        // Broadcast world state
                        c.broadcast("worldUpdate", worldUpdate);
                      }
                    }, 50);
                  },
                  
                  // Add player to game
                  onConnect: async (c) => {
                    const id = c.conn.id;
                    const randomX = Math.floor(Math.random() * c.vars.mapSize);
                    const randomY = Math.floor(Math.random() * c.vars.mapSize);
                    
                    // Create player in memory cache
                    c.vars.playerCache[id] = {
                      id,
                      position: {
                        x: randomX,
                        y: randomY
                      },
                      input: { x: 0, y: 0 }
                    };
                    
                    // Save player to database
                    await c.db
                      .insert(players)
                      .values({
                        id,
                        positionX: randomX,
                        positionY: randomY,
                        inputX: 0,
                        inputY: 0
                      })
                      .onConflictDoUpdate({
                        target: players.id,
                        set: {
                          positionX: randomX,
                          positionY: randomY,
                          inputX: 0,
                          inputY: 0
                        }
                      });
                  },
                  
                  // Remove player from game
                  onDisconnect: async (c) => {
                    const id = c.conn.id;
                    
                    // Remove from memory cache
                    delete c.vars.playerCache[id];
                    
                    // Remove from database
                    await c.db
                      .delete(players)
                      .where(players.id.equals(id));
                  },
                  
                  actions: {
                    // Update movement
                    setInput: async (c, input: Input) => {
                      const id = c.conn.id;
                      const player = c.vars.playerCache[id];
                      
                      if (player) {
                        // Update in memory for fast response
                        player.input = input;
                        
                        // Update in database
                        await c.db
                          .update(players)
                          .set({
                            inputX: input.x,
                            inputY: input.y
                          })
                          .where(players.id.equals(id));
                      }
                    }
                  }
                });

                export default gameRoom;
                ```
              </div>
            </div>

            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">App.tsx</span>
                <span class="file-description">Runs in the browser</span>
              </div>

              <div class="code-block">
                ```tsx
                import { createClient } from "actor-core/client";
                import { createReactActorCore } from "@actor-core/react";
                import { useState, useEffect, useRef } from "react";
                import type { Player } from "./actor";

                const client = createClient("http://localhost:6420");
                const { useActor, useActorEvent } = createReactActorCore(client);

                export function MultiplayerGame() {
                  const [{ actor, connectionId }] = useActor("gameRoom");
                  const [players, setPlayers] = useState<Player[]>([]);
                  const canvasRef = useRef<HTMLCanvasElement>(null);
                  const keysPressed = useRef<Record<string, boolean>>({});
                  
                  // Set up game
                  useEffect(() => {
                    if (!actor) return;
                    
                    // Set up keyboard handlers
                    const handleKeyDown = (e: KeyboardEvent) => {
                      keysPressed.current[e.key.toLowerCase()] = true;
                    };
                    
                    const handleKeyUp = (e: KeyboardEvent) => {
                      keysPressed.current[e.key.toLowerCase()] = false;
                    };
                    
                    window.addEventListener("keydown", handleKeyDown);
                    window.addEventListener("keyup", handleKeyUp);
                    
                    // Input update loop
                    const inputInterval = setInterval(() => {
                      const input = { x: 0, y: 0 };
                      
                      if (keysPressed.current["w"] || keysPressed.current["arrowup"]) input.y = -1;
                      if (keysPressed.current["s"] || keysPressed.current["arrowdown"]) input.y = 1;
                      if (keysPressed.current["a"] || keysPressed.current["arrowleft"]) input.x = -1;
                      if (keysPressed.current["d"] || keysPressed.current["arrowright"]) input.x = 1;
                      
                      actor.setInput(input);
                    }, 50);
                    
                    // Rendering loop
                    const renderLoop = () => {
                      const canvas = canvasRef.current;
                      if (!canvas) return;
                      
                      const ctx = canvas.getContext("2d");
                      if (!ctx) return;
                      
                      ctx.clearRect(0, 0, canvas.width, canvas.height);
                      
                      // Use for loop instead of forEach
                      for (let i = 0; i < players.length; i++) {
                        const player = players[i];
                        ctx.fillStyle = player.id === connectionId ? "blue" : "gray";
                        ctx.beginPath();
                        ctx.arc(player.position.x, player.position.y, 10, 0, Math.PI * 2);
                        ctx.fill();
                      }
                      
                      requestAnimationFrame(renderLoop);
                    };
                    
                    const animationId = requestAnimationFrame(renderLoop);
                    
                    return () => {
                      window.removeEventListener("keydown", handleKeyDown);
                      window.removeEventListener("keyup", handleKeyUp);
                      clearInterval(inputInterval);
                      cancelAnimationFrame(animationId);
                    };
                  }, [actor, connectionId, players]);
                  
                  // Listen for world updates
                  useActorEvent({ actor, event: "worldUpdate" }, ({ players: updatedPlayers }) => {
                    setPlayers(updatedPlayers);
                  });
                  
                  return (
                    <div>
                      <canvas 
                        ref={canvasRef} 
                        width={800} 
                        height={600} 
                        style={{ border: "1px solid black" }}
                      />
                      <p>Move: WASD or Arrow Keys</p>
                    </div>
                  );
                }
                ```
              </div>
            </div>
          </div>
        </div>

        {/* Rate Limiter */}

        <div class="code-panel" data-panel="rate-memory">
          <div class="code-split">
            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">actor.ts</span>
                <span class="file-description">Runs on the server</span>
              </div>

              <div class="code-block">
                ```typescript
                import { actor } from "actor-core";

                // Simple rate limiter - allows 5 requests per minute
                const rateLimiter = actor({
                  state: {
                    count: 0,
                    resetAt: 0
                  },

                  actions: {
                    // Check if request is allowed
                    checkLimit: (c) => {
                      const now = Date.now();
                      
                      // Reset if expired
                      if (now > c.state.resetAt) {
                        c.state.count = 0;
                        c.state.resetAt = now + 60000; // 1 minute window
                      }
                      
                      // Check if under limit
                      const allowed = c.state.count < 5;
                      
                      // Increment if allowed
                      if (allowed) {
                        c.state.count++;
                      }
                      
                      return {
                        allowed,
                        remaining: 5 - c.state.count,
                        resetsIn: Math.round((c.state.resetAt - now) / 1000)
                      };
                    }
                  }
                });

                export default rateLimiter;
                ```
              </div>
            </div>

            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">App.tsx</span>
                <span class="file-description">Runs in the browser</span>
              </div>

              <div class="code-block">
                ```typescript
                import { createClient } from "actor-core/client";
                import { createReactActorCore } from "@actor-core/react";
                import { useState } from "react";
                import type { App } from "../actors/app";

                const client = createClient<App>("http://localhost:6420");
                const { useActor } = createReactActorCore(client);

                export function RateLimiter() {
                  // Connect to API rate limiter for user-123
                  const [{ actor }] = useActor("rateLimiter", { tags: { userId: "user-123" } });
                  const [result, setResult] = useState<{
                    allowed: boolean;
                    remaining: number;
                    resetsIn: number;
                  } | null>(null);
                  
                  // Make a request
                  const makeRequest = async () => {
                    if (!actor) return;
                    
                    const response = await actor.checkLimit();
                    setResult(response);
                  };

                  return (
                    <div>
                      <h2>Rate Limiter (5 req/min)</h2>
                      
                      <button onClick={makeRequest}>Make Request</button>
                      
                      {result && (
                        <div>
                          <p>Status: {result.allowed ? "Allowed" : "Blocked"}</p>
                          <p>Remaining: {result.remaining}</p>
                          <p>Resets in: {result.resetsIn} seconds</p>
                        </div>
                      )}
                    </div>
                  );
                }
                ```
              </div>
            </div>
          </div>
        </div>

        <div class="code-panel" data-panel="rate-sqlite">
          <div class="code-split">
            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">actor.ts</span>
                <span class="file-description">Runs on the server</span>
              </div>

              <div class="code-block">
                ```typescript
                import { actor } from "actor-core";
                import { drizzle } from "@actor-core/drizzle";
                import { limiters } from "./schema";

                // Simple rate limiter - allows 5 requests per minute
                const rateLimiter = actor({
                  sql: drizzle(),

                  actions: {
                    // Check if request is allowed
                    checkLimit: async (c) => {
                      const now = Date.now();
                      
                      // Get the current limiter state from database
                      const limiterState = await c.db
                        .select()
                        .from(limiters)
                        .get();
                      
                      // If no record exists, create one
                      if (!limiterState) {
                        await c.db.insert(limiters).values({
                          count: 1,
                          resetAt: now + 60000 // 1 minute window
                        });
                        
                        return {
                          allowed: true,
                          remaining: 4,
                          resetsIn: 60
                        };
                      }

                      // Reset if expired
                      if (now > limiterState.resetAt) {
                        await c.db.update(limiters)
                          .set({
                            count: 1,
                            resetAt: now + 60000 // 1 minute window
                          });
                        
                        return {
                          allowed: true,
                          remaining: 4,
                          resetsIn: 60
                        };
                      }
                      
                      // Check if under limit
                      const allowed = limiterState.count < 5;
                      
                      // Increment if allowed
                      if (allowed) {
                        await c.db.update(limiters)
                          .set({ count: limiterState.count + 1 });
                      }
                      
                      return {
                        allowed,
                        remaining: 5 - (allowed ? limiterState.count + 1 : limiterState.count),
                        resetsIn: Math.round((limiterState.resetAt - now) / 1000)
                      };
                    }
                  }
                });

                export default rateLimiter;
                ```
              </div>
            </div>

            <div class="code-split-panel">
              <div class="code-panel-title">
                <span class="file-name">App.tsx</span>
                <span class="file-description">Runs in the browser</span>
              </div>

              <div class="code-block">
                ```typescript
                import { createClient } from "actor-core/client";
                import { createReactActorCore } from "@actor-core/react";
                import { useState } from "react";
                import type { App } from "../actors/app";

                const client = createClient<App>("http://localhost:6420");
                const { useActor } = createReactActorCore(client);

                export function RateLimiter() {
                  // Connect to API rate limiter for user-123
                  const [{ actor }] = useActor("rateLimiter", { tags: { userId: "user-123" } });
                  const [result, setResult] = useState<{
                    allowed: boolean;
                    remaining: number;
                    resetsIn: number;
                  } | null>(null);
                  
                  // Make a request
                  const makeRequest = async () => {
                    if (!actor) return;
                    
                    const response = await actor.checkLimit();
                    setResult(response);
                  };

                  return (
                    <div>
                      <h2>Rate Limiter (5 req/min)</h2>
                      
                      <button onClick={makeRequest}>Make Request</button>
                      
                      {result && (
                        <div>
                          <p>Status: {result.allowed ? "Allowed" : "Blocked"}</p>
                          <p>Remaining: {result.remaining}</p>
                          <p>Resets in: {result.resetsIn} seconds</p>
                        </div>
                      )}
                    </div>
                  );
                }
                ```
              </div>
            </div>
          </div>
        </div>
      </div>

      <div class="code-group-disclaimer">
        We're working on publishing full examples related to these snippets. If you find an error, please <a href="https://github.com/rivet-gg/actor-core/issues" target="_blank" rel="noopener noreferrer">create an issue</a>.
      </div>
    </div>
  </div>

  {/*
                    <div style={{ height: '300px' }} />

                    <div className="text-center landing-section">
                    	<h2 className="landing-section-heading">Less Complexity, More Functionality</h2>
                    	<p className="landing-section-text">ActorCore provides a solid foundation with the features you'd expect for modern apps.</p>

                    	<div style={{ height: '80px' }} />

                    	<ComparisonTable />
                    </div>
                    */}

  <div style={{ height: '260px' }} />

  <div className="landing-section">
    <div className="tech-section">
      <div className="tech-section-row">
        <div className="tech-header">
          <h2 className="tech-section-heading">Runs On Your Stack</h2>
          <p className="tech-section-text">Deploy ActorCore anywhere - from serverless platforms to your own infrastructure with our flexible runtime options.</p>
          <p className="tech-section-text">Don't see the runtime you want? <a href="http://localhost:3000/drivers/build">Add your own</a>.</p>
        </div>

        <div className="tech-content">
          <div className="tech-category">
            <h3 className="tech-category-title">All-In-One</h3>

            <div className="tech-buttons-grid">
              <a href="/platforms/rivet" className="tech-button">
                <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/platforms/rivet-white.svg" alt="Rivet" className="tech-icon" noZoom />

                Rivet
              </a>

              <a href="/platforms/cloudflare-workers" className="tech-button">
                <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/platforms/cloudflare-workers.svg" alt="Cloudflare" className="tech-icon" noZoom />

                Cloudflare
              </a>
            </div>
          </div>

          <div className="tech-category">
            <h3 className="tech-category-title">Compute</h3>

            <div className="tech-buttons-grid">
              <a href="https://github.com/rivet-gg/actor-core/issues/897" target="_blank" rel="noopener noreferrer" className="tech-button">
                <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/platforms/vercel.svg" alt="Vercel" className="tech-icon" noZoom />

                Vercel
                <span className="coming-soon">On The Roadmap</span>
              </a>

              <a href="https://github.com/rivet-gg/actor-core/issues/898" target="_blank" rel="noopener noreferrer" className="tech-button">
                <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/platforms/aws-lambda.svg" alt="AWS Lambda" className="tech-icon" noZoom />

                AWS Lambda
                <span className="coming-soon">On The Roadmap</span>
              </a>

              <a href="https://github.com/rivet-gg/actor-core/issues/905" target="_blank" rel="noopener noreferrer" className="tech-button">
                <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/platforms/supabase.svg" alt="Supabase" className="tech-icon" noZoom />

                Supabase
                <span className="help-wanted">Help Wanted</span>
              </a>

              <a href="/platforms/bun" className="tech-button">
                <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/platforms/bun.svg" alt="Bun" className="tech-icon" noZoom />

                Bun
              </a>

              <a href="/platforms/nodejs" className="tech-button">
                <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/platforms/nodejs.svg" alt="Node.js" className="tech-icon" noZoom />

                Node.js
              </a>
            </div>
          </div>

          <div className="tech-category">
            <h3 className="tech-category-title">Storage</h3>

            <div className="tech-buttons-grid">
              <a href="/drivers/redis" className="tech-button">
                <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/platforms/redis.svg" alt="Redis" className="tech-icon" noZoom />

                Redis
              </a>

              <a href="https://github.com/rivet-gg/actor-core/issues/899" target="_blank" rel="noopener noreferrer" className="tech-button">
                <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/platforms/postgres.svg" alt="Postgres" className="tech-icon" noZoom />

                Postgres
                <span className="help-wanted">Help Wanted</span>
              </a>

              <a href="/drivers/file-system" className="tech-button">
                <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/platforms/file-system.svg" alt="File System" className="tech-icon" noZoom />

                File System
              </a>

              <a href="/drivers/memory" className="tech-button">
                <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/platforms/memory.svg" alt="Memory" className="tech-icon" noZoom />

                Memory
              </a>
            </div>
          </div>
        </div>
      </div>

      <div style={{ height: "20px" }} />

      <div className="tech-section-row">
        <div className="tech-header">
          <h2 className="tech-section-heading">Works With Your Tools</h2>
          <p className="tech-section-text">Seamlessly integrate ActorCore with your favorite frameworks, languages, and tools.</p>
          <p className="tech-section-text">Don't see what you need? <a href="https://github.com/rivet-gg/actor-core/issues/new" target="_blank" rel="noopener noreferrer">Request an integration</a>.</p>
        </div>

        <div className="tech-content">
          <div className="tech-category">
            <h3 className="tech-category-title">Frameworks</h3>

            <div className="tech-buttons-grid">
              <a href="/frameworks/react" className="tech-button">
                <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/clients/react.svg" alt="React" className="tech-icon" noZoom />

                React
              </a>

              <a href="https://github.com/rivet-gg/actor-core/issues/904" target="_blank" rel="noopener noreferrer" className="tech-button">
                <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/clients/nextjs.svg" alt="Next.js" className="tech-icon" noZoom />

                Next.js
                <span className="help-wanted">Help Wanted</span>
              </a>

              <a href="https://github.com/rivet-gg/actor-core/issues/903" target="_blank" rel="noopener noreferrer" className="tech-button">
                <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/clients/vue.svg" alt="Vue" className="tech-icon" noZoom />

                Vue
                <span className="help-wanted">Help Wanted</span>
              </a>
            </div>
          </div>

          <div className="tech-category">
            <h3 className="tech-category-title">Clients</h3>

            <div className="tech-buttons-grid">
              <a href="/clients/javascript" className="tech-button">
                <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/clients/javascript.svg" alt="JavaScript" className="tech-icon" noZoom />

                JavaScript
              </a>

              <a href="/clients/javascript" className="tech-button">
                <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/clients/typescript.svg" alt="TypeScript" className="tech-icon" noZoom />

                TypeScript
              </a>

              <a href="https://github.com/rivet-gg/actor-core/issues/900" target="_blank" rel="noopener noreferrer" className="tech-button">
                <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/clients/python.svg" alt="Python" className="tech-icon" noZoom />

                Python
                <span className="coming-soon">Available In April</span>
              </a>

              <a href="/clients/rust" className="tech-button">
                <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/clients/rust.svg" alt="Rust" className="tech-icon" noZoom />

                Rust
              </a>
            </div>
          </div>

          <div className="tech-category">
            <h3 className="tech-category-title">Integrations</h3>

            <div className="tech-buttons-grid">
              <a href="/integrations/hono" className="tech-button">
                <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/integrations/hono.svg" alt="Hono" className="tech-icon" noZoom />

                Hono
              </a>

              <a href="/concepts/testing" className="tech-button">
                <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/integrations/vitest.svg" alt="Vitest" className="tech-icon" noZoom />

                Vitest
              </a>

              <a href="/integrations/resend" className="tech-button">
                <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/integrations/resend.svg" alt="Resend" className="tech-icon" noZoom />

                Resend
              </a>

              <a href="https://github.com/rivet-gg/actor-core/issues/906" target="_blank" rel="noopener noreferrer" className="tech-button">
                <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/integrations/better-auth.svg" alt="Better Auth" className="tech-icon" noZoom />

                Better Auth
                <span className="coming-soon">On The Roadmap</span>
              </a>

              <a href="https://github.com/rivet-gg/actor-core/issues/907" target="_blank" rel="noopener noreferrer" className="tech-button">
                <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/platforms/vercel.svg" alt="AI SDK" className="tech-icon" noZoom />

                AI SDK
                <span className="coming-soon">On The Roadmap</span>
              </a>
            </div>
          </div>

          <div className="tech-category">
            <h3 className="tech-category-title">Local-First Sync</h3>

            <div className="tech-buttons-grid">
              <a href="https://github.com/rivet-gg/actor-core/issues/908" target="_blank" rel="noopener noreferrer" className="tech-button">
                <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/integrations/livestore.svg" alt="LiveStore" className="tech-icon" noZoom />

                LiveStore
                <span className="coming-soon">Available In May</span>
              </a>

              <a href="https://github.com/rivet-gg/actor-core/issues/909" target="_blank" rel="noopener noreferrer" className="tech-button">
                <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/integrations/zerosync.svg" alt="ZeroSync" className="tech-icon" noZoom />

                ZeroSync
                <span className="help-wanted">Help Wanted</span>
              </a>

              <a href="https://github.com/rivet-gg/actor-core/issues/910" target="_blank" rel="noopener noreferrer" className="tech-button">
                <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/integrations/tinybase.svg" alt="TinyBase" className="tech-icon" noZoom />

                TinyBase
                <span className="help-wanted">Help Wanted</span>
              </a>

              <a href="https://github.com/rivet-gg/actor-core/issues/911" target="_blank" rel="noopener noreferrer" className="tech-button">
                <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/integrations/yjs.svg" alt="Yjs" className="tech-icon" noZoom />

                Yjs
                <span className="help-wanted">Help Wanted</span>
              </a>
            </div>
          </div>
        </div>
      </div>

      <div style={{ height: "20px" }} />

      <div className="tech-section-row">
        <div className="tech-header">
          <h2 className="tech-section-heading">Roadmap For 2025</h2>
          <p className="tech-section-text">We ship fast, so we want to share what you can expect to see before the end of the year.</p>
          <p className="tech-section-text">Help shape our roadmap by <a href="https://github.com/rivet-gg/actor-core/issues" target="_blank" rel="noopener noreferrer">creating issues</a> and <a href="https://rivet.gg/discord" target="_blank" rel="noopener noreferrer">joining our Discord</a>.</p>
        </div>

        <div className="tech-content">
          <div className="tech-buttons-grid">
            <div className="tech-button">
              SQLite Support
            </div>

            <div className="tech-button">
              SQLite in Studio
            </div>

            <div className="tech-button">
              Local-First Extensions
            </div>

            <div className="tech-button">
              Auth Extensions
            </div>

            <div className="tech-button">
              Workflows
            </div>

            <div className="tech-button">
              Queues
            </div>

            <div className="tech-button">
              MCP
            </div>

            <div className="tech-button">
              Actor-Actor Actions
            </div>

            <div className="tech-button">
              Cancellable Schedules
            </div>

            <div className="tech-button">
              Cron Jobs
            </div>

            <div className="tech-button">
              Drizzle Support
            </div>

            <div className="tech-button">
              Prisma v7 Support
            </div>

            <div className="tech-button">
              Read Replicas
            </div>

            <div className="tech-button">
              Middleware
            </div>

            <div className="tech-button">
              Schema Validation
            </div>

            <div className="tech-button">
              Vite Integration
            </div>

            <div className="tech-button">
              OpenTelemetry
            </div>

            <div className="tech-button">
              More Examples
            </div>

            <div className="tech-button tech-button-completed">
              Studio

              <span className="tech-completed-icon">
                <Icon icon="check" color="#888" size={12} />
              </span>
            </div>

            <div className="tech-button tech-button-completed">
              File system driver

              <span className="tech-completed-icon">
                <Icon icon="check" color="#888" size={12} />
              </span>
            </div>

            <div className="tech-button tech-button-completed">
              Redis driver

              <span className="tech-completed-icon">
                <Icon icon="check" color="#888" size={12} />
              </span>
            </div>

            <div className="tech-button tech-button-completed">
              Bun support

              <span className="tech-completed-icon">
                <Icon icon="check" color="#888" size={12} />
              </span>
            </div>

            <div className="tech-button tech-button-completed">
              P2P topology

              <span className="tech-completed-icon">
                <Icon icon="check" color="#888" size={12} />
              </span>
            </div>

            <div className="tech-button tech-button-completed">
              React client

              <span className="tech-completed-icon">
                <Icon icon="check" color="#888" size={12} />
              </span>
            </div>

            <div className="tech-button tech-button-completed">
              Rust client

              <span className="tech-completed-icon">
                <Icon icon="check" color="#888" size={12} />
              </span>
            </div>

            <div className="tech-button tech-button-completed">
              Resend Integration

              <span className="tech-completed-icon">
                <Icon icon="check" color="#888" size={12} />
              </span>
            </div>

            <div className="tech-button tech-button-completed">
              Vitest Integration

              <span className="tech-completed-icon">
                <Icon icon="check" color="#888" size={12} />
              </span>
            </div>

            <div className="tech-button tech-button-completed">
              Non-serialized state

              <span className="tech-completed-icon">
                <Icon icon="check" color="#888" size={12} />
              </span>
            </div>

            <div className="tech-button tech-button-completed">
              create-actor

              <span className="tech-completed-icon">
                <Icon icon="check" color="#888" size={12} />
              </span>
            </div>

            <div className="tech-button tech-button-completed">
              actor-core dev

              <span className="tech-completed-icon">
                <Icon icon="check" color="#888" size={12} />
              </span>
            </div>

            <div className="tech-button tech-button-completed">
              Hono Integration

              <span className="tech-completed-icon">
                <Icon icon="check" color="#888" size={12} />
              </span>
            </div>
          </div>
        </div>
      </div>
    </div>
  </div>

  <div style={{ height: '260px' }} />

  <div className="text-center landing-section">
    <h2 className="landing-section-heading">Supercharged Local Development with the Studio</h2>
    <p className="landing-section-text">Like Postman, but for all of your stateful serverless needs.</p>

    <div style={{ height: '40px' }} />

    <div className="youtube-container">
      <iframe src="https://www.youtube-nocookie.com/embed/RYgo25fH9Ss?si=KH-fD6fHP501TTpn" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen />
    </div>

    <div style={{ height: '40px' }} />

    <div className="landing-buttons">
      <a href="https://studio.rivet.gg" className="landing-button landing-button-secondary" target="_blank" rel="noopener noreferrer">
        Visit The Studio
      </a>
    </div>
  </div>

  <div style={{ height: '220px' }} />

  <div className="landing-section">
    {/* Quotes Layout */}

    <div>
      <div className="text-center">
        <h2 className="landing-section-heading">What People Are Saying</h2>
        <p className="landing-section-text">From the platform formerly known as Twitter</p>
      </div>

      <div style={{ height: '40px' }} />

      <div className="quotes-container">
        {/* Column 1 */}

        <div className="quotes-column">
          <a href="https://x.com/devgerred/status/1903178025598083285" className="quote-card" target="_blank" rel="noopener noreferrer">
            <div className="quote-author-section">
              <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/quotes/users/devgerred.jpg" alt="gerred" className="quote-author-avatar" noZoom />

              <div className="quote-author-info">
                <p className="quote-author-name">gerred</p>
                <p className="quote-author-handle">@devgerred</p>
              </div>
            </div>

            <p className="quote-content">Nice work, @rivet\_gg - nailed it</p>
          </a>

          <a href="https://x.com/samk0_com/status/1909278348812952007" className="quote-card" target="_blank" rel="noopener noreferrer">
            <div className="quote-author-section">
              <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/quotes/users/samk0_com.jpg" alt="Samo" className="quote-author-avatar" noZoom />

              <div className="quote-author-info">
                <p className="quote-author-name">Samo</p>
                <p className="quote-author-handle">@samk0\_com</p>
              </div>
            </div>

            <p className="quote-content">Great UX & DX possible thanks to @ActorCore\_org</p>

            <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/quotes/posts/1909278348812952007.png" alt="Tweet media" className="quote-image" noZoom />
          </a>

          <a href="https://x.com/Social_Quotient/status/1903172142121832905" className="quote-card" target="_blank" rel="noopener noreferrer">
            <div className="quote-author-section">
              <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/quotes/users/Social_Quotient.jpg" alt="John Curtis" className="quote-author-avatar" noZoom />

              <div className="quote-author-info">
                <p className="quote-author-name">John Curtis</p>
                <p className="quote-author-handle">@Social\_Quotient</p>
              </div>
            </div>

            <p className="quote-content">Loving ActorCore direction!</p>
          </a>

          <a href="https://x.com/localfirstnews/status/1902752173928427542" className="quote-card" target="_blank" rel="noopener noreferrer">
            <div className="quote-author-section">
              <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/quotes/users/localfirstnews.jpg" alt="Local-First Newsletter" className="quote-author-avatar" noZoom />

              <div className="quote-author-info">
                <p className="quote-author-name">Local-First Newsletter</p>
                <p className="quote-author-handle">@localfirstnews</p>
              </div>
            </div>

            <p className="quote-content"><em>Featured in newsletter</em></p>
          </a>

          <a href="https://x.com/Chinoman10_/status/1902020312306216984" className="quote-card" target="_blank" rel="noopener noreferrer">
            <div className="quote-author-section">
              <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/quotes/users/Chinoman10_.jpg" alt="Chinomso" className="quote-author-avatar" noZoom />

              <div className="quote-author-info">
                <p className="quote-author-name">Chinomso</p>
                <p className="quote-author-handle">@Chinoman10\_</p>
              </div>
            </div>

            <p className="quote-content">Alternatively, some dude (@NathanFlurry) recently told me about @ActorCore\_org, which optionally brings you vendor-flexibility (no lock-in since it's abstracted for you).</p>
          </a>
        </div>

        {/* Column 2 */}

        <div className="quotes-column">
          <a href="https://x.com/uripont_/status/1910817946470916525" className="quote-card" target="_blank" rel="noopener noreferrer">
            <div className="quote-author-section">
              <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/quotes/users/uripont_.jpg" alt="uripont" className="quote-author-avatar" noZoom />

              <div className="quote-author-info">
                <p className="quote-author-name">uripont</p>
                <p className="quote-author-handle">@uripont\_</p>
              </div>
            </div>

            <p className="quote-content">Crazy to think that there are so many things to highlight that is actually hard to convey it in a few words.</p>
          </a>

          <a href="https://x.com/samgoodwin89/status/1910791029609091456" className="quote-card" target="_blank" rel="noopener noreferrer">
            <div className="quote-author-section">
              <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/quotes/users/samgoodwin89.jpg" alt="sam" className="quote-author-avatar" noZoom />

              <div className="quote-author-info">
                <p className="quote-author-name">sam</p>
                <p className="quote-author-handle">@samgoodwin89</p>
              </div>
            </div>

            <p className="quote-content">"Durable Objects without the boilerplate"</p>
          </a>

          <a href="https://x.com/j0g1t/status/1902835527977439591" className="quote-card" target="_blank" rel="noopener noreferrer">
            <div className="quote-author-section">
              <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/quotes/users/j0g1t.jpg" alt="Kacper Wojciechowski" className="quote-author-avatar" noZoom />

              <div className="quote-author-info">
                <p className="quote-author-name">Kacper Wojciechowski</p>
                <p className="quote-author-handle">@j0g1t</p>
              </div>
            </div>

            <p className="quote-content">Your outie uses @ActorCore\_org to develop realtime applications.</p>

            <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/quotes/posts/1902835527977439591.jpg" alt="Tweet media" className="quote-image" noZoom />
          </a>

          <a href="https://x.com/alistaiir/status/1891312940302716984" className="quote-card" target="_blank" rel="noopener noreferrer">
            <div className="quote-author-section">
              <img src="https://mintlify.s3.us-west-1.amazonaws.com/rivet-c4d395ab/images/quotes/users/alistaiir.jpg" alt="alistair" className="quote-author-avatar" noZoom />

              <div className="quote-author-info">
                <p className="quote-author-name">alistair</p>
                <p className="quote-author-handle">@alistaiir</p>
              </div>
            </div>

            <p className="quote-content">ActorCore looks super awesome.</p>
          </a>
        </div>
      </div>

      <div style={{ height: '40px' }} />

      {/* Tweet Button */}

      <div className="text-center">
        <a href="https://twitter.com/intent/tweet?text=%40ActorCore_org%20" className="tweet-button" target="_blank" rel="noopener noreferrer">
          Share your feedback on X <Icon icon="arrow-right" color="white" />
        </a>
      </div>
    </div>
  </div>

  <div style={{ height: '260px' }} />

  <div className="text-center landing-section">
    <h2 className="landing-section-heading">Join the Community</h2>
    <p className="landing-section-text">Help make ActorCore the universal way to build & scale stateful serverless applications.</p>

    <div style={{ height: '40px' }} />

    <div className="tech-buttons-grid" style={{ maxWidth: '600px', margin: '0 auto', display: 'grid', gridTemplateColumns: 'repeat(3, 1fr)', gap: '16px' }}>
      <a href="https://rivet.gg/discord" className="tech-button" target="_blank" rel="noopener noreferrer">
        <Icon icon="discord" color="#5865F2" className="tech-icon" />

        Discord
      </a>

      <a href="https://x.com/ActorCore_org" className="tech-button" target="_blank" rel="noopener noreferrer">
        <Icon icon="x-twitter" color="white" className="tech-icon" />

        X
      </a>

      <a href="https://bsky.app/profile/rivet.gg" className="tech-button" target="_blank" rel="noopener noreferrer">
        <Icon icon="bluesky" color="#0085FF" className="tech-icon" />

        Bluesky
      </a>

      <a href="https://github.com/rivet-gg/actor-core/discussions" className="tech-button" target="_blank" rel="noopener noreferrer">
        <Icon icon="github" color="white" className="tech-icon" />

        Discussions
      </a>

      <a href="https://github.com/rivet-gg/actor-core/issues" className="tech-button" style={{ gridColumn: '2' }} target="_blank" rel="noopener noreferrer">
        <Icon icon="github" color="white" className="tech-icon" />

        Issues
      </a>
    </div>
  </div>

  <div style={{ height: '260px' }} />

  <div className="landing-section">
    <div className="text-center">
      <h2 id="faq" className="landing-section-heading">Frequently Asked Questions</h2>
      <p className="landing-section-text">Common questions about stateful serverless and ActorCore.</p>

      <div style={{ height: '40px' }} />

      <div className="faq-section">
        <div className="faq-accordion" data-state="closed">
          <button className="faq-question">
            How is ActorCore different than Rivet Actors?

            <Icon icon="chevron-down" size={16} color="white" />
          </button>

          <div className="faq-answer">
            <p>ActorCore is a framework written in TypeScript that provides high-level functionality. Rivet is an open-source serverless platform written in Rust with features tailored for stateful serverless.</p>
            <p>You can think of it as ActorCore is to Rivet as Next.js is to Vercel.</p>
            <p>While Rivet is the primary maintainer of ActorCore, we intend for this to be community driven.</p>
          </div>
        </div>

        <div className="faq-accordion" data-state="closed">
          <button className="faq-question">
            How does stateful serverless compare to the traditional actor model?

            <Icon icon="chevron-down" size={16} color="white" />
          </button>

          <div className="faq-answer">
            <p>Stateful serverless is very similar to actors: it's essentially actors with persistence, and usually doesn't have as rigid constraints on message handling. This makes it more flexible while maintaining the core benefits of the actor model.</p>
          </div>
        </div>

        <div className="faq-accordion" data-state="closed">
          <button className="faq-question">
            How do stateful and stateless serverless work together?

            <Icon icon="chevron-down" size={16} color="white" />
          </button>

          <div className="faq-answer">
            <p>Stateless serverless works well when you have an external resource that maintains state. Stateful serverless, on the other hand, is almost like a mini-database.</p>
            <p>Sometimes it makes sense to use stateless serverless to make requests to multiple stateful serverless instances, orchestrating complex operations across multiple state boundaries.</p>
          </div>
        </div>

        <div className="faq-accordion" data-state="closed">
          <button className="faq-question">
            How does ActorCore achieve huge performance gains?

            <Icon icon="chevron-down" size={16} color="white" />
          </button>

          <div className="faq-answer">
            <p>By storing state in memory and flushing to a persistence layer, we can serve requests instantly instead of waiting for a round trip to the database. There are additional optimizations that can be made around your state to tune the durability of it.</p>
            <p>Additionally, data is stored near your users at the edge, ensuring round-trip times of less than 50ms when they request it. This edge-first approach eliminates the latency typically associated with centralized databases.</p>
          </div>
        </div>

        <div className="faq-accordion" data-state="closed">
          <button className="faq-question">
            Isn't well-designed software supposed to separate compute and storage?

            <Icon icon="chevron-down" size={16} color="white" />
          </button>

          <div className="faq-answer">
            <p>Some software makes sense to separate – e.g., for data lakes or highly relational data. But at the end of the day, data has to be partitioned somewhere at some point.</p>
            <p>Usually "faster" databases like Cassandra, DynamoDB, or Vitess make consistency tradeoffs to get better performance. Stateful serverless forces you to think about how your data is sharded for better performance, better scalability, and less consistency footguns.</p>
          </div>
        </div>

        <div className="faq-accordion" data-state="closed">
          <button className="faq-question">
            What is stateful serverless not good for?

            <Icon icon="chevron-down" size={16} color="white" />
          </button>

          <div className="faq-answer">
            <p>OLAP, data lakes, graph databases, and highly relational data are currently not ideal use cases for stateful serverless, though it will get better at handling these use cases over time.</p>
          </div>
        </div>

        <div className="faq-accordion" data-state="closed">
          <button className="faq-question">
            Can this create a single bottleneck?

            <Icon icon="chevron-down" size={16} color="white" />
          </button>

          <div className="faq-answer">
            <p>Yes, but only as much as storing data in a single database row does. We're working on building out read replicas to allow you to perform read-only actions on actors.</p>
          </div>
        </div>

        <div className="faq-accordion" data-state="closed">
          <button className="faq-question">
            Stateless serverless is standardized under WinterTC. Is there any intention to standardize stateful serverless?

            <Icon icon="chevron-down" size={16} color="white" />
          </button>

          <div className="faq-answer">
            <p>Things are cooking! Check out our <a href="https://rivet.gg/blog/2025-03-23-what-would-a-w3c-standard-look-like-for-stateful-serverless-" target="_blank">blog post</a> about what a W3C standard for stateful serverless might look like and <a href="https://x.com/threepointone/status/1903579571028390038" target="_blank">the awesome people who are collaborating on this</a>.</p>
          </div>
        </div>
      </div>

      <div style={{ height: '40px' }} />

      <div className="text-center">
        <p className="text-lg">
          Have more questions? Join our <a href="https://discord.gg/rivet" className="text-primary hover:text-primary-dark">Discord</a> or go to <a href="https://github.com/rivet-gg/actor-core/discussions" className="text-primary hover:text-primary-dark">GitHub Discussions</a>.
        </p>
      </div>
    </div>
  </div>

  <div style={{ height: '260px' }} />

  <div className="landing-section">
    <div className="manifesto-section">
      <h2 class="landing-section-heading">Why We Created ActorCore</h2>

      <p class="landing-section-text">
        Stateful serverless is the future of how applications will be architected.
      </p>

      <p class="landing-section-text">
        Startups increasingly build on <span class="highlight">stateful serverless</span> to <span class="highlight">ship faster</span>, achieve <span class="highlight">better performance</span>, and <span class="highlight">outscale databases like Postgres</span>. The <span class="highlight">actor model</span> – closely related to stateful serverless – has an established history in frameworks like <span class="highlight">Elixir</span>, <span class="highlight">Orleans</span>, and <span class="highlight">Akka</span>, though these typically involve steep learning curves and complex infrastructure. Cloudflare demonstrates the power of this approach, having <span class="highlight">built their entire infrastructure</span> – including R2, Workflows, and Queues – on their stateful serverless engine called Durable Objects.
      </p>

      <p class="landing-section-text">
        With years of experience in <span class="highlight">gaming infrastructure</span>, we've seen firsthand how the <span class="highlight">stateful serverless model</span> excels. After building numerous systems like matchmaking, chat, presence, and social networks using stateful serverless, <span class="highlight">we're convinced it's hands down the best way to build applications</span>. However, <span class="highlight">the ecosystem lacks accessibility and resources</span>.
      </p>

      <p class="landing-section-text">
        To popularize stateful serverless, we decided to build something that works for everyone. <span class="highlight">No vendor lock-in</span>, <span class="highlight">no steep learning curve</span>, and a <span class="highlight">community-driven approach</span> that brings the best ideas from different ecosystems together.
      </p>

      <p class="landing-section-text">
        At <span class="highlight">Rivet</span>, we maintain an <span class="highlight">open-source runtime</span> to run stateful serverless workloads – including ActorCore. We see maintaining ActorCore as a <span class="highlight">rising tide</span>: more people will build applications this way, and we hope to provide the best deployment, monitoring, and collaboration solution for this architecture.
      </p>

      <div class="signature">
        <a href="https://x.com/NathanFlurry" target="_blank" rel="noopener noreferrer" class="signature-name">Nathan Flurry</a>, <a href="https://x.com/NicholasKissel" target="_blank" rel="noopener noreferrer" class="signature-name">Nicholas Kissel</a>, and the Rivet Team
      </div>
    </div>
  </div>

  <div style={{ height: '260px' }} />

  <div className="cta-section landing-section">
    <h2 className="cta-title" id="rotating-cta-title">Performance in every act - thanks to ActorCore.</h2>

    <div style={{ height: "16px" }} />

    <div className="landing-buttons">
      <a href="/overview" className="landing-button landing-button-primary">
        Get Started
      </a>

      <a href="https://github.com/rivet-gg/actor-core" target="_blank" className="landing-button landing-button-secondary">
        View on GitHub
      </a>
    </div>

    <div style={{ height: "8px" }} />

    <p className="cta-pun-complaint">Click here to file a complaint for bad puns.</p>
  </div>
</div>


# Using Claude Code with ActorCore
Source: https://actorcore.org/llm/claude



[Claude Code](https://claude.ai/code) is a powerful CLI tool from Anthropic that integrates Claude directly into your development workflow. When working with ActorCore, you can enhance Claude's understanding of the codebase by providing project-specific context.

## Setting Up CLAUDE.md for ActorCore

The `CLAUDE.md` file serves as a memory file for Claude Code, containing important information about your project that persists between sessions.

To set up an effective `CLAUDE.md` file for ActorCore:

<Steps>
  <Step title="Get the template">
    Copy the ActorCore [prompt.txt](/llm/prompt)
  </Step>

  <Step title="Create file">
    Create a `CLAUDE.md` file in your project root
  </Step>

  <Step title="Add content">
    Paste the template into `CLAUDE.md`
  </Step>

  <Step title="Verify it works">
    Run Claude Code and ask a simple question like `What lifecycle hook is used when an actor is first created?` to confirm it's reading your CLAUDE.md file correctly
  </Step>
</Steps>

## Example Commands for ActorCore

Here are some useful ways to leverage Claude Code with ActorCore:

### Understand the Codebase

```bash
# Get an overview of ActorCore's architecture
claude "explain the architecture of ActorCore and how the different topologies work"

# Understand how actors communicate
claude "explain how actors communicate with each other in the coordinate topology"

# Learn about specific concepts
claude "explain the lifecycle hooks for actors and when each one is called"
```

### Find Relevant Code

```bash
# Find implementations of specific components
claude "find the files that implement the Redis driver"

# Locate examples of specific patterns
claude "show me examples of RPC methods in the codebase"

# Understand actor state management
claude "explain how actor state is persisted between restarts"
```

### Add New Features

```bash
# Create a new actor implementation
claude "help me create a new actor for managing user sessions"

# Add authentication to an actor
claude "show me how to add authentication to my actor's _onBeforeConnect method"

# Implement error handling
claude "help me implement proper error handling for my actor's RPC methods"
```

### Debug Issues

```bash
# Diagnose connection problems
claude "my actor connections are dropping, help me debug why"

# Fix state persistence issues
claude "my actor state isn't persisting between restarts, what could be wrong?"

# Address scaling problems
claude "my actors are using too much memory, how can I optimize them?"
```

## Additional Resources

* [Claude Code Documentation](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview)
* [Claude Code Tutorials](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/tutorials)


# Using Cursor with ActorCore
Source: https://actorcore.org/llm/cursor



This guide shows how to integrate ActorCore with Cursor to enhance your developer experience through AI-assisted coding.

## Setting Up Cursor Rules for ActorCore

Cursor rules allow you to customize how the AI assistant behaves when working with ActorCore code. By providing project-specific context, you'll get more accurate and relevant suggestions.

### Project Rules (Recommended)

Project rules are stored in the `.cursor/rules` directory and apply to specific files or folders in your project.

<Steps>
  <Step title="Open project">Open your ActorCore project in Cursor</Step>

  <Step title="Create rule">
    Press `Cmd + Shift + P` (Mac) or `Ctrl + Shift + P` (Windows/Linux).

    Select `New Cursor Rule` and name it `actorcore-development-guide`.
  </Step>

  <Step title="Configure rule">
    Set `Auto Attach` to `**/*.ts`.

    Paste [prompt.txt](/llm/prompt) into the rule.
  </Step>
</Steps>

### Global Rules

If you frequently work with ActorCore across multiple projects, you can add ActorCore-specific rules globally:

<Steps>
  <Step title="Open settings">
    Open Cursor and go to `Cursor Settings` > `Rules` > `User Rules`
  </Step>

  <Step title="Add content">
    Paste [prompt.txt](/llm/prompt) into the textbox
  </Step>
</Steps>

Global rules will apply to all of your projects when using Cursor.

## Example Queries for ActorCore

Here are some useful prompts to try with Cursor when working with ActorCore:

### Understand the Codebase

```
# Get an overview of ActorCore's architecture
Explain the architecture of ActorCore and how the different topologies work

# Understand how actors communicate
Explain how actors communicate with each other in the coordinate topology

# Learn about specific concepts
Explain the lifecycle hooks for actors and when each one is called
```

### Find Relevant Code

```
# Find implementations of specific components
Find the files that implement the Redis driver

# Locate examples of specific patterns
Show me examples of RPC methods in the codebase

# Understand actor state management
Explain how actor state is persisted between restarts
```

### Add New Features

```
# Create a new actor implementation
Help me create a new actor for managing user sessions

# Add authentication to an actor
Show me how to add authentication to my actor's _onBeforeConnect method

# Implement error handling
Help me implement proper error handling for my actor's RPC methods
```

### Debug Issues

```
# Diagnose connection problems
My actor connections are dropping, help me debug why

# Fix state persistence issues
My actor state isn't persisting between restarts, what could be wrong?

# Address scaling problems
My actors are using too much memory, how can I optimize them?
```

## Additional Resources

* [Cursor Rules Documentation](https://docs.cursor.com/context/rules-for-ai)


# Docs As Markdown for LLMs
Source: https://actorcore.org/llm/docs-as-markdown



ActorCore documentation is designed to be easily accessible for Large Language Models (LLMs). All documentation pages are automatically available as plain Markdown files by simply appending `.md` to the URL.

## How to Access

To access any ActorCore documentation page as Markdown:

1. Navigate to the regular documentation URL (e.g., `https://actorcore.org/concepts/state`)
2. Append `.md` to the URL (e.g., `https://actorcore.org/concepts/state.md`)

This will return the raw Markdown content of the documentation page.

## Use Cases

This feature enables seamless integration with AI tools by providing documentation in clean Markdown format. Key uses include:

* **Context for LLM chats**: Importing relevant docs into LLM chat sessions for specific context
* **Web crawling**: Enabling efficient crawling of documentation content
* **AI agents**: Building AI agents with access to ActorCore documentation

## Additional Resources

* [prompt.txt](/llm/prompt)
* [llms.txt](/llm/llms)
* [llms-full.txt](/llm/llms-full)


# llms.txt
Source: https://actorcore.org/llm/llms





# llms-full.txt
Source: https://actorcore.org/llm/llms-full





# prompt.txt
Source: https://actorcore.org/llm/prompt



## Using `prompt.txt` for ActorCore

The `prompt.txt` file provides LLMs with comprehensive information about ActorCore's conventions, terminology, and best practices. To use it:

1. Copy the contents below to your clipboard
2. Paste it into your preferred AI assistant (Claude, ChatGPT, Cursor rules, Windsurf Rules, etc.)
3. Ask your ActorCore development questions after the prompt

This structured information helps AI tools provide more accurate and contextually relevant guidance for your ActorCore development tasks.

## AI Editor Guides

Read the integration guide for your editor of choice:

<CardGroup cols={3}>
  <Card title="Cursor" href="/llm/cursor" horizontal={true} />

  <Card title="Windsurf" href="/llm/windsurf" horizontal={true} />

  <Card title="Claude Code" href="/llm/claude" horizontal={true} />
</CardGroup>

## `prompt.txt`

```markdown prompt.txt
# ActorCore Development Guide

This guide contains essential information for working with the ActorCore project.

## Project Naming and Terminology

- Use `ActorCore` when referring to the project in documentation and plain English
- Use `actor-core` (kebab-case) when referring to the project in code, package names, and imports

### Core Concepts

- **Actor**: A stateful, long-lived entity that processes messages and maintains state
- **Manager**: Component responsible for creating, routing, and managing actor instances
- **Action**: Method for an actor to expose callable functions to clients
- **Event**: Asynchronous message sent from an actor to connected clients
- **Alarm**: Scheduled callback that triggers at a specific time

## Build Commands

- **Type Check:** `yarn check-types` - Verify TypeScript types
- **Check specific package:** `yarn check-types -F actor-core` - Check only specified package
- **Build:** `yarn build` - Production build using Turbopack
- **Build specific package:** `yarn build -F actor-core` - Build only specified package
- **Format:** `yarn fmt` - Format code with Biome

## Driver Implementations

Available driver implementations:

- **Memory**: In-memory implementation for development and testing
- **Redis**: Production-ready implementation using Redis for persistence and pub/sub
- **Cloudflare Workers**: Uses Durable Objects for actor state persistence
- **Rivet**: Fully-managed cloud platform with built-in scaling and monitoring

## Platform Support

ActorCore supports multiple runtime environments:

- **NodeJS**: Standard Node.js server environment
- **Cloudflare Workers**: Edge computing environment
- **Bun**: Fast JavaScript runtime alternative to Node.js
- **Rivet**: Cloud platform with built-in scaling and management

## Package Import Resolution

When importing from workspace packages, always check the package's `package.json` file under the `exports` field to determine the correct import paths:

1. Locate the package's `package.json` file
2. Find the `exports` object which maps subpath patterns to their file locations
3. Use these defined subpaths in your imports rather than direct file paths

## Code Style Guidelines

- **Formatting:** Uses Biome for consistent formatting
- **Imports:** Organized imports enforced, unused imports warned
- **TypeScript:** Strict mode enabled, target ESNext
- **Naming:** 
  - camelCase for variables, functions
  - PascalCase for classes, interfaces, types
  - UPPER_CASE for constants
- **Error Handling:** 
  - Use `UserError` for client-safe errors
  - Use `InternalError` for internal errors

## Project Structure

- Monorepo with Yarn workspaces and Turborepo
- Core code in `packages/actor-core/`
- Platform implementations in `packages/platforms/`
- Driver implementations in `packages/drivers/`

## State Management

- Each actor owns and manages its own isolated state via `c.state`
- State is automatically persisted between action calls
- State is initialized via `createState` function or `state` constant
- Only JSON-serializable types can be stored in state
- Use `onStateChange` to react to state changes

## Authentication and Security

- Authentication is handled through the `onBeforeConnect` lifecycle hook
- Connection state is accessed with `c.conn.state`
- Access control should be implemented for each action
- Throwing an error in `onBeforeConnect` will abort the connection
- Use `UserError` for safe error messages to clients
- Use data validation libraries like zod for input validation

## Actions and Events

- **Actions**: Used for clients to call actor functions
- **Events**: For actors to publish updates to clients
- Actions are defined in the `actions` object of the actor configuration
- Helper functions outside the `actions` object are not callable by clients
- Broadcasting is done via `c.broadcast(name, data)`
- Specific client messaging uses `conn.send(name, data)`
- Clients subscribe to events with `actor.on(eventName, callback)`

## Lifecycle Hooks

- `createState()`: Function that returns initial actor state
- `onStart(c)`: Called any time actor is started (after restart/upgrade)
- `onStateChange(c, newState)`: Called when actor state changes
- `onBeforeConnect(c)`: Called when new client connects
- `onConnect(c)`: Executed after client connection succeeds
- `onDisconnect(c)`: Called when client disconnects

## Actor Management

- App is configured with actors using `setup({ actors: { actorName }})` followed by `serve(app)`
- Actors are accessed by client using `client.actorName.get()`
- Actors can pass an ID parameter or object with `client.actorName.get(id)` or `client.actorName.get({key: value})`
- Actors can be shut down with `c.shutdown()` from within the actor

## Scaling and Architecture Guidelines

- Each actor should have a single responsibility
- Keep state minimal and relevant to the actor's core function
- Use separate actors for different entity types (users, rooms, documents)
- Avoid too many cross-actor communications
- Use appropriate topology based on your scaling needs

## Scheduling

- Schedule future events with `c.after(duration, fn, ...args)`
- Schedule events for specific time with `c.at(timestamp, fn, ...args)`
- Scheduled events persist across actor restarts

## CORS Configuration

- Configure CORS to allow cross-origin requests in production
- Set allowed origins, methods, headers, and credentials
- For development, use `cors: { origin: "http://localhost:3000" }`

## Development Best Practices

- Prefer functional actor pattern with `actor({ ... })` syntax
- Use zod for runtime type validation
- Use `assertUnreachable(x: never)` for exhaustive type checking
- Add proper JSDoc comments for public APIs
- Run `yarn check-types` regularly during development
- Use `tsx` CLI to execute TypeScript scripts directly
```


# Using Windsurf with ActorCore
Source: https://actorcore.org/llm/windsurf



This guide shows how to integrate ActorCore with Windsurf to enhance your developer experience through AI-assisted coding.

## Setting Up Windsurf Rules for ActorCore

Windsurf rules allow you to customize how the AI assistant (Cascade) behaves when working with ActorCore code. By providing project-specific context, you'll get more accurate and relevant suggestions.

### Workspace Rules (Recommended)

Workspace rules are stored in the `.windsurfrules` file in your project root and apply to your local workspace.

<Steps>
  <Step title="Open project">Open your ActorCore project in Windsurf</Step>

  <Step title="Create rules file">
    Navigate to "Windsurf - Settings" (at the bottom right) > "Settings" > "Cascade" > "Set Workspace AI Rules" and click "Edit Rules."

    This will create a `.windsurfrules` file in your project root.
  </Step>

  <Step title="Configure rules">
    Paste [prompt.txt](/llm/prompt) into the `.windsurfrules` file.
  </Step>
</Steps>

### Global Rules

If you frequently work with ActorCore across multiple projects, you can add ActorCore-specific rules globally:

<Steps>
  <Step title="Open settings">
    Navigate to "Windsurf - Settings" (at the bottom right) > "Settings" > "Cascade" > "Set Global AI Rules" and click "Edit Rules."
  </Step>

  <Step title="Add content">
    Paste [prompt.txt](/llm/prompt) into the `global_rules.md` file.
  </Step>
</Steps>

Global rules will apply to all of your projects when using Windsurf.

## Example Queries for ActorCore

Here are some useful prompts to try with Windsurf when working with ActorCore:

### Understand the Codebase

```
# Get an overview of ActorCore's architecture
Explain the architecture of ActorCore and how the different topologies work

# Understand how actors communicate
Explain how actors communicate with each other in the coordinate topology

# Learn about specific concepts
Explain the lifecycle hooks for actors and when each one is called
```

### Find Relevant Code

```
# Find implementations of specific components
Find the files that implement the Redis driver

# Locate examples of specific patterns
Show me examples of RPC methods in the codebase

# Understand actor state management
Explain how actor state is persisted between restarts
```

### Add New Features

```
# Create a new actor implementation
Help me create a new actor for managing user sessions

# Add authentication to an actor
Show me how to add authentication to my actor's _onBeforeConnect method

# Implement error handling
Help me implement proper error handling for my actor's RPC methods
```

### Debug Issues

```
# Diagnose connection problems
My actor connections are dropping, help me debug why

# Fix state persistence issues
My actor state isn't persisting between restarts, what could be wrong?

# Address scaling problems
My actors are using too much memory, how can I optimize them?
```

## Additional Resources

* [Windsurf Rules Documentation](https://docs.codeium.com/windsurf/memories#windsurfrules)


# Documentation Overview
Source: https://actorcore.org/overview



ActorCore is a framework for building stateful, scalable, realtime backend applications. Whether you're building multiplayer games, collaborative apps, AI agent backends, or any stateful service, ActorCore provides the tools and patterns to simplify your architecture.

{/*## What are actors good for?

  Actors in ActorCore are ideal for applications requiring:

  - **Stateful Services**: Applications where maintaining state across interactions is critical. For example, **Collaborative Apps** with shared editing and automatic persistence.
  - **Realtime Systems**: Applications requiring fast, in-memory state modifications or push updates to connected clients. For example, **Multiplayer Games** with game rooms and player state.
  - **Long-Running Processes**: Tasks that execute over extended periods or in multiple steps. For example, **AI Agents** with ongoing conversations and stateful tool calls.
  - **Durability**: Processes that must survive crashes and restarts without data loss. For example, **Durable Execution** workflows that continue after system restarts.
  - **Horizontal Scalability**: Systems that need to scale by distributing load across many instances. For example, **Realtime Stream Processing** for stateful event handling.
  - **Local-First Architecture**: Systems that synchronize state between offline clients. For example, **Local-First Sync** between devices.*/}

## Core Concepts

In ActorCore, each actor has these key characteristics:

* **State Is Automatically Persisted**: State automatically persists between restarts, upgrades, & crashes
* **State Is Stored In-Memory**: State is stored in memory for high-performance reads/writes while also automatically persisted
* **Isolated State Ownership**: Actors only manage their own state, which can only be modified by the actor itself
* **Communicates via Actions**: How clients and other actors interact with an actor
* **Actions Are Low-Latency**: Actions provide WebSocket-like performance for time-sensitive operations
* **Broadcast Updates With Events**: Actors can publish real-time updates to connected clients

## Get Started

Integrate ActorCore with your project:

<CardGroup cols={2}>
  <Card title="React" icon="react" href="/frameworks/react">
    Seamlessly connect React applications to your ActorCore backend with ready-to-use hooks and components.
  </Card>

  <Card title="Node.js & Bun" icon="node-js" href="/clients/javascript">
    Connect to ActorCore from any JavaScript application with the official client library.
  </Card>

  <Card title="Rust" icon="rust" href="/clients/rust">
    High-performance Rust client for systems programming and game development.
  </Card>
</CardGroup>

## Deploy

Choose your platform to deploy ActorCore:

<CardGroup cols={2}>
  <Card title="Rivet" href="/platforms/rivet">
    Deploy ActorCore applications on Rivet's purpose-built cloud platform with built-in scaling and management.
  </Card>

  <Card title="Cloudflare Workers" href="/platforms/cloudflare-workers">
    Run ActorCore at the edge with Cloudflare Workers for global low-latency applications.
  </Card>

  <Card title="Bun" href="/platforms/bun">
    Use ActorCore with the fast Bun JavaScript runtime for performance-focused development.
  </Card>

  <Card title="Node.js" href="/platforms/nodejs">
    Run ActorCore in traditional Node.js environments for maximum compatibility.
  </Card>
</CardGroup>

## Concepts

Learn the core concepts that power ActorCore applications:

<CardGroup cols={2}>
  <Card title="Overview" icon="square-info" href="/concepts/overview">
    Introduction to ActorCore concepts and architecture.
  </Card>

  <Card title="Interacting with Actors" icon="square-code" href="/concepts/interacting-with-actors">
    Learn how to connect to and interact with actors from clients.
  </Card>

  <Card title="State" icon="floppy-disk" href="/concepts/state">
    Understand how actor state is managed, persisted, and accessed.
  </Card>

  <Card title="Actions" icon="bolt" href="/concepts/actions">
    Define and implement actor actions (RPCs) for client interaction.
  </Card>

  <Card title="Events" icon="tower-broadcast" href="/concepts/events">
    Real-time communication with events and broadcasts.
  </Card>

  <Card title="Lifecycle" icon="rotate" href="/concepts/lifecycle">
    Managing the creation, execution, and termination of actors.
  </Card>

  <Card title="Schedule" icon="clock" href="/concepts/schedule">
    Schedule tasks and alarms with actors for time-based operations.
  </Card>

  <Card title="Authentication" icon="fingerprint" href="/concepts/authentication">
    Implement secure authentication for your ActorCore applications.
  </Card>
</CardGroup>

### More Concepts

<CardGroup cols={2}>
  <Card title="Connections" icon="network-wired" href="/concepts/connections">
    Manage client connections and sessions with actors.
  </Card>

  <Card title="Metadata" icon="tag" href="/concepts/metadata">
    Working with actor metadata for discovery and organization.
  </Card>

  <Card title="Testing" icon="vial" href="/concepts/testing">
    Comprehensive testing strategies for ActorCore applications.
  </Card>

  <Card title="Logging" icon="file-lines" href="/concepts/logging">
    Implement logging for debugging and monitoring.
  </Card>

  <Card title="CORS" icon="globe" href="/concepts/cors">
    Configure Cross-Origin Resource Sharing for web clients.
  </Card>

  <Card title="Scaling" icon="arrow-up-right-dots" href="/concepts/scaling">
    Strategies for scaling ActorCore applications horizontally.
  </Card>

  <Card title="External SQL" icon="table" href="/concepts/external-sql">
    Integrate with external SQL databases for additional persistence.
  </Card>

  <Card title="Types" icon="code" href="/concepts/types">
    Type system and validation in ActorCore for robust applications.
  </Card>

  <Card title="Topology" icon="diagram-project" href="/concepts/topology">
    Understanding actor topology models for distributed systems.
  </Card>
</CardGroup>

## Reference

Integrate ActorCore with Large Language Models:

<CardGroup cols={2}>
  <Card title="Cursor" href="/llm/cursor">
    Use Cursor AI coding assistant with ActorCore.
  </Card>

  <Card title="Windsurf" href="/llm/windsurf">
    Windsurf AI integration with ActorCore.
  </Card>

  <Card title="Claude Code" href="/llm/claude">
    Claude AI integration with ActorCore.
  </Card>

  <Card title="Docs as Markdown" href="/llm/docs-as-markdown">
    Use ActorCore docs as markdown with LLMs for better assistance.
  </Card>

  <Card title="prompts.txt" href="/llm/prompt">
    Prompting best practices for ActorCore with LLMs.
  </Card>

  <Card title="llms.txt" href="/llms.txt">
    General LLM integration guide for ActorCore.
  </Card>

  <Card title="llms-full.txt Full" href="/llms-full.txt">
    Comprehensive LLM integration guide for advanced use cases.
  </Card>
</CardGroup>

## Support

<CardGroup cols={2}>
  <Card title="GitHub Issues" icon="bug" href="https://github.com/rivet-gg/actor-core/issues">
    Report bugs and request features on GitHub.
  </Card>

  <Card title="GitHub Discussions" icon="comments" href="https://github.com/rivet-gg/actor-core/discussions">
    Join the community discussions for help and ideas.
  </Card>

  <Card title="Changelog" icon="list-check" href="https://github.com/rivet-gg/actor-core/releases">
    Stay up-to-date with the latest ActorCore releases.
  </Card>

  <Card title="Discord" icon="discord" href="https://rivet.gg/discord">
    Join the Rivet Discord server to chat with the community.
  </Card>

  <Card title="Enterprise" icon="building" href="/support/enterprise">
    Learn about enterprise support options for ActorCore.
  </Card>
</CardGroup>


# Bun
Source: https://actorcore.org/platforms/bun



Bun provides a fast runtime environment for running ActorCore, with excellent performance for both development and production.

<Info>
  ActorCore is still pre-v1.0. Please help us by report bugs on [GitHub Issues](https://github.com/rivet-gg/actor-core/issues)!
</Info>

## Deploy

<Steps>
  <Step title="Start with framework">
    Start with your framework of choice:

    <CardGroup cols={2}>
      <Card title="React" icon="react" href="/frameworks/react" />

      <Card title="Node.js & Bun" icon="node-js" href="/clients/javascript" />

      <Card title="Rust" icon="rust" href="/clients/rust" />
    </CardGroup>
  </Step>

  <Step title="Install dependencies">
    Install the Bun platform package:

    ```sh
    bun add @actor-core/bun
    ```
  </Step>

  <Step title="Define your server">
    Create a file `src/index.ts` to start your ActorCore server:

    ```typescript src/index.ts
    import { serve } from "@actor-core/bun";
    import { app } from "../actors/app";

    // Start the server with file-system driver (default)
    serve(app);
    ```
  </Step>

  <Step title="Deploy to production">
    Build and run your production server:

    ```sh
    bun build ./src/index.ts --outdir ./dist
    bun ./dist/index.js
    ```

    Deploy to any cloud provider of your choice.
  </Step>

  <Step title="Update your client's endpoint">
    Update your client to connect to your deployed app:

    <CodeGroup>
      ```typescript TypeScript
      const client = createClient<App>(/* FILL ME IN */);
      ```

      ```rust Rust
      let client = Client::new(/* FILL ME IN */, TransportKind::WebSocket, EncodingKind::Cbor);
      ```
    </CodeGroup>
  </Step>
</Steps>

## CORS Configuration

For security reasons, you should configure proper CORS settings in production. In the example above, we used `cors: { origin: "*" }` which allows requests from any domain.

For production deployments, specify the exact domains that should be allowed to connect to your actors. Learn more in the [CORS documentation](/concepts/cors).

## Integration with Existing Projects

If you already have an existing application and want to mount ActorCore on a subpath, see our [Hono integration guide](/integrations/hono). Remember to specify the same path in `config.basePath` as where you mount the router.

## Using Different Drivers

By default, ActorCore for Bun uses the file-system driver, which persists state between restarts.

For simple deployments, you can switch between drivers with:

```typescript
serve(app, {
  mode: "in-memory",  // Switch to in-memory (file-system is default)
});
```

For production, consider using an alternative driver like [Redis](/drivers/redis).

## Available Regions

Bun typically runs in a single region at a time. For multi-region deployments, consider:

* [Rivet](/platforms/rivet) - Managed cloud service with global deployment
* [Cloudflare Workers](/platforms/cloudflare-workers) - Edge computing with global distribution

## Next Steps

<CardGroup>
  <Card title="Overview" href="/concepts/overview" icon="square-plus" horizontal={true} />

  <Card title="Interacting with Actors" href="/concepts/interacting-with-actors" icon="square-plus" horizontal={true} />

  <Card title="Actions" href="/concepts/actions" icon="bolt" horizontal={true} />

  <Card title="State" href="/concepts/state" icon="floppy-disk" horizontal={true} />
</CardGroup>


# Cloudflare Workers (Durable Objects)
Source: https://actorcore.org/platforms/cloudflare-workers



The Cloudflare Workers platform with Durable Objects provides a robust environment for running ActorCore at the edge.

<Info>
  ActorCore is still pre-v1.0. Please help us by report bugs on [GitHub Issues](https://github.com/rivet-gg/actor-core/issues)!
</Info>

## Deploy

<Steps>
  <Step title="Start with framework">
    Start with your framework of choice:

    <CardGroup cols={2}>
      <Card title="React" icon="react" href="/frameworks/react" />

      <Card title="Node.js & Bun" icon="node-js" href="/clients/javascript" />

      <Card title="Rust" icon="rust" href="/clients/rust" />
    </CardGroup>
  </Step>

  <Step title="Install dependencies">
    Install the Cloudflare Workers platform package:

    <CodeGroup>
      ```sh npm
      npm install @actor-core/cloudflare-workers
      ```

      ```sh pnpm
      pnpm add @actor-core/cloudflare-workers
      ```

      ```sh yarn
      yarn add @actor-core/cloudflare-workers
      ```

      ```sh bun
      bun add @actor-core/cloudflare-workers
      ```
    </CodeGroup>
  </Step>

  <Step title="Create your server">
    Create a file `src/index.ts` to handle Cloudflare Workers integration:

    ```typescript src/index.ts
    import { createHandler } from "@actor-core/cloudflare-workers";
    import { app } from "../actors/app";

    // Create handlers for Cloudflare Workers
    const { handler, ActorHandler } = createHandler(app);

    // Export the handlers for Cloudflare
    export { handler as default, ActorHandler };
    ```
  </Step>

  <Step title="Create KV namespace">
    Create a KV namespace for your actors:

    ```sh
    npx wrangler kv:namespace create ACTOR_KV
    ```

    Take note of the KV namespace ID from the output, as you'll need it in the next step.
  </Step>

  <Step title="Configure Wrangler">
    Create a `wrangler.jsonc` configuration and add your KV namespace ID from the previous step:

    ```json wrangler.jsonc
    {
      "$schema": "node_modules/wrangler/config-schema.json",
      "name": "my-app",
      "main": "src/index.ts",
      "compatibility_date": "2025-04-04",
      "observability": {
        "enabled": true
      },
      "migrations": [
        {
          "tag": "v1",
          "new_classes": ["ActorHandler"]
        }
      ],
      "durable_objects": {
        "bindings": [
          {
            "name": "ACTOR_DO",
            "class_name": "ActorHandler"
          }
        ]
      },
      "kv_namespaces": [
        {
          "binding": "ACTOR_KV",
          "id": "your-namespace-id-here"  // Replace with your actual ID
        }
      ]
    }
    ```
  </Step>

  <Step title="Deploy to production">
    Deploy your project to Cloudflare Workers:

    ```sh
    npx wrangler deploy
    ```

    Your ActorCore application will be available at your Cloudflare Workers URL.
  </Step>

  <Step title="Update your client's endpoint">
    Update your client to connect to your deployed app:

    <CodeGroup>
      ```typescript TypeScript
      const client = createClient<App>(/* FILL ME IN */);
      ```

      ```rust Rust
      let client = Client::new(/* FILL ME IN */, TransportKind::WebSocket, EncodingKind::Cbor);
      ```
    </CodeGroup>
  </Step>
</Steps>

## CORS Configuration

For security reasons, you should configure proper CORS settings in production. In the example above, we used `cors: { origin: "*" }` which allows requests from any domain.

For production deployments, specify the exact domains that should be allowed to connect to your actors. Learn more in the [CORS documentation](/concepts/cors).

## Integration with Existing Projects

If you already have an existing application and want to mount ActorCore on a subpath, see our [Hono integration guide](/integrations/hono). Remember to specify the same path in `config.basePath` as where you mount the router.

## Accessing Cloudflare Context And Bindings

You can access Cloudflare-specific features like the [DurableObjectState](https://developers.cloudflare.com/durable-objects/api/state/) and environment bindings from your actor:

```typescript
import { actor } from "actor-core";

const myActor = actor({
  // Load Cloudflare-specific variables
  createVars: (c, cloudflare) => ({
    ctx: cloudflare.ctx,
    env: cloudflare.env,
  }),
  actions: {
    foo: async (c) => {
      // Access DurableObjectState
      await c.vars.ctx.storage.get("foo");

      // Access bindings
      await c.vars.env.MY_BUCKET.put(key, "foo");
    },
  }
});
```

## Available Regions

See available regions [here](https://developers.cloudflare.com/durable-objects/reference/data-location/#supported-locations-1).

Cloudflare does not guarantee your code will run in the requested region.

## Next Steps

<CardGroup>
  <Card title="Overview" href="/concepts/overview" icon="square-plus" horizontal={true} />

  <Card title="Interacting with Actors" href="/concepts/interacting-with-actors" icon="square-plus" horizontal={true} />

  <Card title="Actions" href="/concepts/actions" icon="bolt" horizontal={true} />

  <Card title="State" href="/concepts/state" icon="floppy-disk" horizontal={true} />
</CardGroup>


# Node.js
Source: https://actorcore.org/platforms/nodejs



Node.js provides a robust environment for running ActorCore, ideal for development and production deployments.

<Info>
  ActorCore is still pre-v1.0. Please help us by report bugs on [GitHub Issues](https://github.com/rivet-gg/actor-core/issues)!
</Info>

## Deploy

<Steps>
  <Step title="Start with framework">
    Start with your framework of choice:

    <CardGroup cols={2}>
      <Card title="React" icon="react" href="/frameworks/react" />

      <Card title="Node.js & Bun" icon="node-js" href="/clients/javascript" />

      <Card title="Rust" icon="rust" href="/clients/rust" />
    </CardGroup>
  </Step>

  <Step title="Install dependencies">
    Install the Node.js platform package:

    <CodeGroup>
      ```sh npm
      npm install @actor-core/nodejs
      ```

      ```sh pnpm
      pnpm add @actor-core/nodejs
      ```

      ```sh yarn
      yarn add @actor-core/nodejs
      ```

      ```sh bun
      bun add @actor-core/nodejs
      ```
    </CodeGroup>
  </Step>

  <Step title="Define your server">
    Create a file `src/index.ts` to start your ActorCore server:

    ```typescript src/index.ts
    import { serve } from "@actor-core/nodejs";
    import { app } from "../actors/app";

    // Start the server with file-system driver (default)
    serve(app);
    ```
  </Step>

  <Step title="Deploy to production">
    Compile your TypeScript code and run the server:

    ```sh
    npx -p typescript tsc
    node dist/index.js
    ```

    Deploy to any cloud provider of your choice.
  </Step>

  <Step title="Update your client's endpoint">
    Update your client to connect to your deployed app:

    <CodeGroup>
      ```typescript TypeScript
      const client = createClient<App>(/* FILL ME IN */);
      ```

      ```rust Rust
      let client = Client::new(/* FILL ME IN */, TransportKind::WebSocket, EncodingKind::Cbor);
      ```
    </CodeGroup>
  </Step>
</Steps>

## CORS Configuration

For security reasons, you should configure proper CORS settings in production. In the example above, we used `cors: { origin: "*" }` which allows requests from any domain.

For production deployments, specify the exact domains that should be allowed to connect to your actors. Learn more in the [CORS documentation](/concepts/cors).

## Integration with Existing Projects

If you already have an existing application and want to mount ActorCore on a subpath, see our [Hono integration guide](/integrations/hono). Remember to specify the same path in `config.basePath` as where you mount the router.

## Using Different Drivers

By default, ActorCore for Node.js uses the file-system driver, which persists state between restarts.

For simple deployments, you can switch between drivers with:

```typescript
serve(app, {
  mode: "in-memory",  // Switch to in-memory (file-system is default)
});
```

For production, consider using an alternative driver like [Redis](/drivers/redis).

## Available Regions

Node.js typically runs in a single region at a time. For multi-region deployments, consider:

* [Rivet](/platforms/rivet) - Managed cloud service with global deployment
* [Cloudflare Workers](/platforms/cloudflare-workers) - Edge computing with global distribution

## Next Steps

<CardGroup>
  <Card title="Overview" href="/concepts/overview" icon="square-plus" horizontal={true} />

  <Card title="Interacting with Actors" href="/concepts/interacting-with-actors" icon="square-plus" horizontal={true} />

  <Card title="Actions" href="/concepts/actions" icon="bolt" horizontal={true} />

  <Card title="State" href="/concepts/state" icon="floppy-disk" horizontal={true} />
</CardGroup>


# Rivet
Source: https://actorcore.org/platforms/rivet



Rivet provides a fully managed cloud service for running ActorCore, with automatic scaling, global deployment, and built-in monitoring.

<Info>
  ActorCore is still pre-v1.0. Please help us by report bugs on [GitHub Issues](https://github.com/rivet-gg/actor-core/issues)!
</Info>

## Deploy

<Steps>
  <Step title="Start with framework">
    Start with your framework of choice:

    <CardGroup cols={2}>
      <Card title="React" icon="react" href="/frameworks/react" />

      <Card title="Node.js & Bun" icon="node-js" href="/clients/javascript" />

      <Card title="Rust" icon="rust" href="/clients/rust" />
    </CardGroup>
  </Step>

  <Step title="Install dependencies">
    Install the Rivet platform package:

    <CodeGroup>
      ```sh npm
      npm install @actor-core/rivet
      ```

      ```sh pnpm
      pnpm add @actor-core/rivet
      ```

      ```sh yarn
      yarn add @actor-core/rivet
      ```

      ```sh bun
      bun add @actor-core/rivet
      ```
    </CodeGroup>
  </Step>

  <Step title="Deploy to production">
    Deploy your ActorCore application to Rivet:

    <CodeGroup>
      ```sh npm
      npx @actor-core/cli@latest deploy rivet actors/app.ts
      ```

      ```sh pnpm
      pnpm exec @actor-core/cli@latest deploy rivet actors/app.ts
      ```

      ```sh yarn
      yarn @actor-core/cli@latest deploy rivet actors/app.ts
      ```

      ```sh bun
      bunx @actor-core/cli@latest deploy rivet actors/app.ts
      ```
    </CodeGroup>

    This will:

    1. Prompt you to log in to Rivet if needed
    2. Ask you to select or create a Rivet project
    3. Build and deploy your application
    4. Provide you with your new endpoint

       Update your client code with the new endpoint URL and test your deployed application.
  </Step>

  <Step title="Update your client's endpoint">
    Update your client to connect to your deployed app:

    <CodeGroup>
      ```typescript TypeScript
      const client = createClient<App>(/* FILL ME IN */);
      ```

      ```rust Rust
      let client = Client::new(/* FILL ME IN */, TransportKind::WebSocket, EncodingKind::Cbor);
      ```
    </CodeGroup>
  </Step>
</Steps>

## CORS Configuration

For security reasons, you should configure proper CORS settings in production. In the example above, we used `cors: { origin: "*" }` which allows requests from any domain.

For production deployments, specify the exact domains that should be allowed to connect to your actors. Learn more in the [CORS documentation](/concepts/cors).

## Integration with Existing Projects

If you already have an existing application and want to mount ActorCore on a subpath, see our [Hono integration guide](/integrations/hono). Remember to specify the same path in `config.basePath` as where you mount the router.

## Accessing Rivet Context

[Rivet's `ActorContext`](https://rivet.gg/docs/javascript-runtime#the-actor-context-object) can be accessed from `createVars`.

```typescript
import { actor } from "actor-core";

const myActor = actor({
  // Load Rivet-specific variables
  createVars: (c, rivet) => ({
    rivet: rivet.ctx,
  }),
  actions: {
    foo: async (c) => {
      // Access ActorContext
      c.log.info(`Region: ${c.vars.rivet.metadata.region.name}`);
      await c.vars.rivet.kv.get("foo");
    },
  }
});
```

## Available Regions

Rivet supports deploying your actors to multiple regions automatically. You can specify region preferences in your Rivet project settings in the Rivet Hub.

See available regions [here](https://rivet.gg/docs/regions).

## Next Steps

<CardGroup>
  <Card title="Overview" href="/concepts/overview" icon="square-plus" horizontal={true} />

  <Card title="Interacting with Actors" href="/concepts/interacting-with-actors" icon="square-plus" horizontal={true} />

  <Card title="Actions" href="/concepts/actions" icon="bolt" horizontal={true} />

  <Card title="State" href="/concepts/state" icon="floppy-disk" horizontal={true} />
</CardGroup>


# Enterprise
Source: https://actorcore.org/support/enterprise



ActorCore is developed and maintained by [Rivet](https://rivet.gg), offering comprehensive enterprise support and deployment solutions tailored to your organization's needs.

Our enterprise services include:

* Dedicated technical support
* Custom deployment configurations
* Training and implementation assistance

For enterprise inquiries, please contact our solutions team at [rivet.gg/sales](https://rivet.gg/sales).