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

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

​
Quickstart

1

Create a new Node.js project

Create a new Node.js project with TypeScript support:

mkdir my-app
cd my-app
npm init -y
npm pkg set type=module
2

Install ActorCore packages

Install the ActorCore client and Node.js platform packages:

npm install actor-core
3

Define your actor

Create a file actors/app.ts in your project with your actor definition:

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

Create your client

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

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

Start your ActorCore development server

Launch the development server with:

npx @actor-core/cli@latest dev actors/app.ts

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.

6

Run your client

In a separate terminal, run your client code:

npx tsx src/client.ts

You should see output like:

Event: 5
Action: 5

Run it again to see the state update.

7

Deploy your ActorCore app

Now that you have your project running, deploy your application to one of these platforms:

Rivet

Cloudflare Workers

Bun

Node.js

​
Next Steps

See the Interacting with Actors documentation for information on how to use the client.