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

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

Quickstart

1

Create a new React project

Create a new React project with TypeScript support:

npm create vite@latest my-app -- --template react-ts
2

Install ActorCore packages

Navigate to your React project and install the ActorCore client and React packages:

cd my-app
npm install actor-core @actor-core/react
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

Build your React frontend

Now modify your src/App.tsx file to connect to your ActorCore backend:

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

Start your React app

In a separate terminal, start your React app:

cd my-app
npm run dev

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) to see your application.

7

Deploy your ActorCore app

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

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.

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.

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.

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

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