ActorCore is still pre-v1.0. Please help us by report bugs on GitHub Issues!

​
Create New Project

1

Create Project with CLI

Run this command:

bun
bun create actor@latest

Follow the prompts:

  1. Where would you like to create your project? - Choose your project directory
  2. To which platform would you like to deploy? - Select Bun
  3. Which template would you like to use? - Select counter, or your template of choice

The CLI will set up your project and install all dependencies automatically.

2

Start Development Server

Start your development server with:

cd your-project
bun dev

This will start your ActorCore server in development mode.

3

Test

In a separate terminal, run the auto-generated test client:

bun tests/client.ts
# Outputs:
# Event: 5
# Action: 5

Run this again to see the state update.

4

Deploy

To build for production:

bun build
bun start

Request a guide for deploying Bun to your preferred cloud provider on GitHub Discussions.

​
Integrating With Existing Projects

If you already have a Bun project and want to add ActorCore, you can follow these steps for manual integration. This approach gives you more control over how ActorCore fits into your existing codebase.

1

Install Bun

Install Bun here.

2

Install Packages

# Install ActorCore
bun add actor-core @actor-core/bun
3

Create Actor

Create a new file for your actor at src/app.ts:

src/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: "http://localhost:8080" }
});

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

Create Entrypoint

Create src/index.ts to start your ActorCore server with:

src/index.ts
import { setup, createHandler } from "@actor-core/bun"
import { app } from "./app";

// Create a handler for HTTP requests
export default createHandler(app);

If you already have an existing application and want to mount ActorCore on a subpath, see our Hono integration guide. Remember to specify the same path in config.basePath as where you mount the router.

5

Create Client

Create a client to connect to your actor in src/client.ts:

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

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

	const counter = await client.counter.get();

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

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

	await counter.dispose();
}

main();
6

Test

Start your development server with:

bun src/index.ts

Then run the client in another terminal with:

bun src/client.ts
# Outputs:
# Event: 5
# Action: 5

Run this again to see the state update.

​
Available Regions

Bun can only run in one region at the moment. See Rivet and Cloudflare Workers for supporting multiple regions.

​
Next Steps

Overview

Interacting with Actors

Actions

State