durable-objects

Extend the DurableObject class from cloudflare:workers, initialize tables inside the constructor using ctx.blockConcurrencyWhile with ctx.storage.sql.exec, and register the class in wrangler migrations using new_sqlite_classes.

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 newUniqueId() when you need a fresh instance.

SQLite storage is recommended for new classes and is configured via new_sqlite_classes in wrangler migrations. KV storage remains for legacy classes, so inspect the backend of existing classes before choosing APIs.

Use Cloudflare's Vitest integration to run Durable Objects in the Workers runtime. Write RPC tests for object behavior, verify state persists across calls, and use the documented test helpers to trigger alarms without 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 strong consistency.

blockConcurrencyWhile blocks all other requests until it completes, so using it on every request kills throughput. It should only wrap schema initialization in the constructor and must never span fetch() calls or external I/O.