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, which are typed public class methods callable directly on the stub, when your compatibility date is 2024-04-03 or later. Reserve fetch handlers for WebSocket upgrades and HTTP-specific needs.

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 are designed for coordination and strong consistency per entity.

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 DO supports one alarm at a time, and calling setAlarm replaces any existing alarm. The alarm handler runs at the scheduled time with automatic retries on failure, so handlers should be idempotent and can reschedule themselves for recurring work.