@sigx/actors-cloudflare · Preview

Installation#

One binding, one migration line, and one define — each of which fails in a way that is hard to diagnose if you miss it.

Install#

Terminal

pnpm add @sigx/actors-cloudflare
pnpm add -D wrangler

npm install @sigx/actors-cloudflare
npm install -D wrangler

yarn add @sigx/actors-cloudflare
yarn add -D wrangler

bun add @sigx/actors-cloudflare
bun add -D wrangler

`wrangler.jsonc`#

JSONC

{
    "main": "src/worker.ts",
    // Pinned, never floating: a compatibility date is how Workers versions
    // runtime behaviour, so bumping it is a deliberate change to test.
    "compatibility_date": "2026-07-01",
    "compatibility_flags": ["nodejs_compat"],

    "durable_objects": {
        "bindings": [{ "name": "ACTORS", "class_name": "ActorHost" }]
    },

    "migrations": [{ "tag": "v1", "new_sqlite_classes": ["ActorHost"] }],

    "define": { "__DEV__": "false" },

    "observability": { "enabled": true }
}

The three that bite#

new_sqlite_classes, not new_classes — a one-way door. new_classes creates the legacy key-value backed storage, which cannot be migrated to SQLite in place; the class is stuck with it forever, and it carries a far smaller per-value limit. This is the single most consequential irreversible line in the file.

__DEV__ must be defined by your bundler. The published package ships both a dev and a production dist and expects the flag to be defined. Without it the host throws __DEV__ is not defined on the first request. pnpm dev should override it to true for local warnings.

nodejs_compat is required. Interleaving needs AsyncLocalStorage.

The entry#

TypeScript

export class ActorHost extends createHostDurableObject<Env>({
    actors, namespace: (env) => env.ACTORS, app: createApp,
}) {}

export default createWorkerHandler<Env>({
    actors, namespace: (env) => env.ACTORS, app: createApp,
    fetch: { origin: false, fallback: servePage },
});

Pass an app factory, not an app — building at module scope binds whichever object constructed it first. And set origin explicitly: the public mount defaults to refusing a request with no Origin, and Workers callers send none.

Both are explained in Cloudflare Workers.

Types#

Env is worth declaring by hand rather than generating with wrangler types — one binding is not worth a generated file that has to be committed, kept in step with wrangler.jsonc and excluded from lint.