durable-objects

Extend the DurableObject class from cloudflare:workers and initialize tables inside the constructor using ctx.blockConcurrencyWhile with ctx.storage.sql.exec. Configure the binding in wrangler.jsonc and add a migration with new_sqlite_classes listing your class name.

Use env.MY_DO.getByName("room-123") for deterministic routing so the same name always maps to the same instance. For existing IDs use idFromString with get(), and for new entities use newUniqueId() while storing the mapping externally.

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

Use Cloudflare's Vitest integration to run Durable Objects in the Workers runtime, testing RPC methods for object behavior and HTTP routes for Worker contracts. Verify state persists across calls, different identities stay independent, and use the documented alarm helpers instead of waiting for wall-clock time.

Calling blockConcurrencyWhile on every request serializes all concurrency and kills throughput. It should only wrap one-time initialization like schema setup in the constructor, and must never span fetch() calls or external I/O.