React

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

​

Quickstart

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

cd my-app
npm install actor-core @actor-core/react

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;

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

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

cd my-app
npm run dev

​

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