Cloudflare Actors

This project is in active development.

We are building a full-featured framework that makes developing Cloudflare Durable Objects easier by introducing new patterns and out of the box functionality that help developers.

Features

• Request Handler to easily define entrypoints to your Actor, Worker, or Request
• Lifecycle Methods enable you to tap into important lifecycle events
• Persistent Properties that store property values between requests and evictions
• RPC Interface into other Actors with a simple MyActor.get('id') interface
• Managing Instances track, delete, and access all instances that have been created
• Location Placement allow you to control the location of your Actor
• SQL Migrations to apply migrations to the SQLite storage
• Multiple Alarms set any number of alarms by timestamp, delay, or cron
• Retry utilities to retry operations using exponential backoff with jitter strategy, and to detect if Durable Object errors are retryable.

And many more features, check out the Examples for more information.

Getting Started

Step 1: Install the package

npm i @cloudflare/actors

Step 2: Update your Wrangler Configuration

Notice the code class name in your Typescript implementation must match the binding name, class_name and new_sqlite_classes value in the configuration. Verify all of the values match.

{
  "migrations": [
    {
      "new_sqlite_classes": ["MyActor"],
      "tag": "v1"
    }
  ],
  "durable_objects": {
    "bindings": [
      {
        "class_name": "MyActor",
        "name": "MyActor"
      }
    ]
  }
}

Step 3: Create your class implementation:

import { Actor, handler } from "@cloudflare/actors";

export class MyActor extends Actor<Env> {
  async onRequest(request: Request): Promise<Response> {
    return new Response("Hello, World!");
  }
}

export default handler(MyActor);

Step 4: Deploy

npm run deploy

Examples

• Basic Example
• Request Handler
• RPC Interface
• Managing Instances
• Lifecycle Hooks
• Location Placement
• How to use without Actor class

FAQ

Alarms

Cold Start:

• [Callback]
• onInit
• onAlarm

Warm Start:

• onAlarm
• [Callback]

For the warm start instance, onInit would have already been called earlier before the alarm trigger.

General

Location Placement

See FAQ for more answers to common questions.

Contributing

We welcome contributions! Please refer to our Contributing Guidelines for more information.

License

This project is licensed under the MIT License - see the LICENSE file for details.