durable-objects

Extend the DurableObject class from cloudflare:workers and initialize tables inside the constructor using ctx.blockConcurrencyWhile with ctx.storage.sql.exec. Register the class in wrangler migrations using new_sqlite_classes and bind it under durable_objects.bindings.

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 unique instances use newUniqueId() while storing the mapping externally.

SQLite storage is recommended for new Durable Object classes and is configured via new_sqlite_classes in migrations. Legacy KV storage remains for existing classes, so inspect the backend of an existing class before choosing APIs.

Use Cloudflare's Vitest integration to run Durable Objects in the Workers runtime, testing RPC methods, storage persistence, and alarms. Verify state survives across calls, different identities stay independent, and use the documented alarm helper instead of waiting for wall-clock time.

Avoid Durable Objects for stateless request handling, workloads needing maximum global distribution, or high fan-out independent requests. Plain Workers fit those cases better since Durable Objects are designed for coordination and strongly consistent per-entity state.

blockConcurrencyWhile blocks all other requests to the instance until it completes, so using it on every request kills throughput. Reserve it for one-time schema initialization in the constructor and never hold it across fetch calls or external I/O.