Create an Actor

Create an actor to run backend logic for a live session that multiple clients share, such as a chat room or a multiplayer game. An actor handles client connections, messages, and disconnections from your backend.

Actor files

Create actors as TypeScript files in your project’s actors directory. Each actor lives in its own subdirectory under base44/actors/ with an entry.ts file:

base44

actors

chatRoom

entry.ts

The folder name becomes the actor name in the SDK and determines how clients call the actor, for example base44.actors.chatRoom. Export the actor class as the default export from the entry.ts file. You can include additional .ts, .js, .json, and .jsonc files in the actor directory and import them from entry.ts.

entry.ts

The code file contains your actor class. Import Actor from base44:runtime/actors and export a class that extends Actor as the default export. Pass Incoming and Outgoing generics to type the messages the actor receives and sends. Implement the following class methods. The handleStart() method is optional:

handleStart(): Load saved session data from storage into class fields. Base44 calls this handler each time the session activates, so your restored state is ready before Base44 handles any connection. For a full storage example, see persist session data.
handleConnect(): Send the current session state to the connecting client. To reject connections or identify clients, see manage client connections.
handleMessage(): Update session state, persist the state, and broadcast the change.
handleClose(): Remove any state tied to that connection. If there’s no connection state to clear, write an empty body.
handleTick(): Run code on each tick interval. If the actor doesn’t use ticks, write an empty body. To set up ticks, see run ticks. To schedule a one-time wake, see schedule wakes.

The following example shows a simplified ChatRoom actor:

import { Actor } from "base44:runtime/actors";

type Incoming = { type: "message"; text: string };
type Outgoing =
  | { type: "history"; messages: string[] }
  | { type: "message"; text: string };

export default class ChatRoom extends Actor<Incoming, Outgoing> {
  messages: string[] = [];

  async handleStart() {
    this.messages = (await this.storage.get<string[]>("messages")) ?? [];
  }

  async handleConnect(conn) {
    conn.send({ type: "history", messages: this.messages });
  }

  async handleMessage(_conn, msg) {
    this.messages.push(msg.text);
    await this.storage.put("messages", this.messages);
    this.broadcast({ type: "message", text: msg.text });
  }

  async handleClose(_conn) {}

  async handleTick() {}
}

Overview

Quickstarts

Project

AI Development Tools

Resources

Actor files

entry.ts

See also

​Actor files

​entry.ts

​See also

Actor files

entry.ts

See also