Durable Objects
Use Durable Objects when one named object should serialize access to its own
state. Retrieve current Cloudflare documentation for APIs, bindings, storage,
class lifecycle, limits, and pricing.
Load only the relevant reference:
- rules.md for partitioning, storage, concurrency, RPC,
alarms, and WebSockets.
- testing.md for Workers Vitest and alarm tests.
- workers.md for bindings, lifecycle configuration,
generated types, and observability.
Design contract
- Name the coordination key and deterministic object ID. Avoid a global object
unless deliberate low-volume global serialization is the requirement.
- Identify object-owned persistent state. Treat caches and external stores as
separate consistency boundaries.
- Prefer typed RPC for new internal interfaces; retain
fetch() when HTTP
semantics or a live compatibility contract requires it.
- Keep state transitions deterministic. External I/O can interleave, so fence,
serialize, or reconcile the affected transition.
- Use
blockConcurrencyWhile() for bounded initialization, not routine requests
or slow external work.
- Remember that one object has one alarm. Persist progress, make the handler
idempotent, and define bounded failure handling.
- Design for constructor reruns and eviction. In-memory state is not durable.
Verify the exact class export, binding target, lifecycle declaration, and live
path touched by the change. Test only the relevant concurrency, restart, alarm,
or WebSocket behavior.
1---2name: durable-objects3description: Design, implement, debug, or test Cloudflare Durable Objects when the task specifically involves per-key coordination, strongly consistent object-owned state, RPC or HTTP interfaces, alarms, WebSocket hibernation, bindings, or class lifecycle. Do not trigger for ordinary stateless Workers or Cloudflare Agents SDK work already owned by the `agents-sdk` skill.4---56# Durable Objects78Use Durable Objects when one named object should serialize access to its own9state. Retrieve current Cloudflare documentation for APIs, bindings, storage,10class lifecycle, limits, and pricing.1112Load only the relevant reference:1314- [rules.md](references/rules.md) for partitioning, storage, concurrency, RPC,15 alarms, and WebSockets.16- [testing.md](references/testing.md) for Workers Vitest and alarm tests.17- [workers.md](references/workers.md) for bindings, lifecycle configuration,18 generated types, and observability.1920## Design contract21221. Name the coordination key and deterministic object ID. Avoid a global object23 unless deliberate low-volume global serialization is the requirement.242. Identify object-owned persistent state. Treat caches and external stores as25 separate consistency boundaries.263. Prefer typed RPC for new internal interfaces; retain `fetch()` when HTTP27 semantics or a live compatibility contract requires it.284. Keep state transitions deterministic. External I/O can interleave, so fence,29 serialize, or reconcile the affected transition.305. Use `blockConcurrencyWhile()` for bounded initialization, not routine requests31 or slow external work.326. Remember that one object has one alarm. Persist progress, make the handler33 idempotent, and define bounded failure handling.347. Design for constructor reruns and eviction. In-memory state is not durable.3536Verify the exact class export, binding target, lifecycle declaration, and live37path touched by the change. Test only the relevant concurrency, restart, alarm,38or WebSocket behavior.
swyxio