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:

npx 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 Node.js
  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
npm run dev

This will start your ActorCore server in development mode.

3

Test

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

npx tsx tests/client.ts
# Outputs:
# Event: 5
# RPC: 5

Run this again to see the state update.

4

Deploy

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

​
Integrate With Existing Projects

If you already have a Node.js 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 Packages

# Install ActorCore
npm add actor-core @actor-core/nodejs
2

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;
3

Create Entrypoint

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

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

serve(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.

4

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();
5

Test

Start your development server with:

npx tsx src/index.ts

Then run the client in another terminal with:

npx tsx src/client.ts
# Outputs:
# Event: 5
# Action: 5

Run this again to see the state update.

​
Available Regions

Node.js 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