durable-objects

Extend the DurableObject class from cloudflare:workers and configure new_sqlite_classes in your wrangler migrations. Initialize tables inside the constructor using ctx.blockConcurrencyWhile, then run synchronous queries via this.ctx.storage.sql.exec.

Use @cloudflare/vitest-pool-workers with defineWorkersConfig pointing at your wrangler config. Access stubs via env from cloudflare:test, inspect internals with runInDurableObject, and trigger alarms instantly with runDurableObjectAlarm.

Use RPC methods with compatibility date 2024-04-03 or later. Public class methods become typed RPC endpoints callable directly on the stub, giving you type safety that a manual fetch handler does not provide.

Avoid Durable Objects for stateless request handling, which plain Workers handle better, and for workloads needing maximum global distribution or high fan-out of independent requests. DOs excel at coordination, strong consistency, and per-entity state.

blockConcurrencyWhile blocks all concurrency in the instance, so using it on every request caps throughput at roughly 200 requests per second. Reserve it for one-time constructor initialization and never hold it across external fetch or I/O calls.

Each Durable Object supports one alarm at a time, and calling setAlarm replaces any existing alarm. The alarm handler runs on schedule with automatic retries on failure, so handlers should be idempotent and can reschedule themselves for recurring work.