Stateful APIs at the edge with Durable Objects

Stateless Workers scale easily, but some features need strongly consistent state: counters, presence, turn-based games, per-document locks, or chat rooms. Durable Objects give you a single-threaded instance addressed by ID - the right primitive when “last write wins in KV” is not enough.

Start with the Durable Counter experiment, then graduate to richer DO apps in the catalog.

Cloudflare products in this patternCopy Anchor Link

When to reach for Durable ObjectsCopy Anchor Link

Use a DO when you need one logical entity with serialized access:

• Per-user or per-room state
• Coordinating multiple clients over WebSockets
• Alarms / deferred work tied to that entity
• SQLite storage colocated with the object (DO SQLite Notes)

Prefer KV, D1, or R2 when entities are independent and eventual consistency is fine. Prefer Queues / Workflows when the problem is async fan-out rather than a sticky entity.

Official overview: What are Durable Objects?

Mental modelCopy Anchor Link

Client → Worker stub → idFromName("room-42") → Durable Object instance

All requests for the same ID hit the same instance. That is the feature: no distributed lock service for the common case.

Read:

• Workers binding / how to access a DO
• Object IDs and naming

The counter teaches:

1. Exporting a DO class from the Worker
2. Binding it in wrangler.json
3. Getting a stub by name/id
4. Reading/writing storage transactionally via the storage API

From counter to real productsCopy Anchor Link

Copy one pattern at a time. A chat app that also invents a novel storage layer on day one is how experiments become unmaintainable.

Design tips from the product docsCopy Anchor Link

• Name IDs carefully - idFromName is a permanent partition key for that name (ID docs)
• Keep handlers small - do heavy AI/fetch work in the Worker or a Queue; coordinate in the DO
• Use storage transactions for multi-key updates (storage API)
• Alarms for deferred cleanup or digests instead of external cron when state-local (alarms)
• Hibernation - understand WebSocket hibernation if you build long-lived realtime (WebSockets + hibernation)

Anti-patternsCopy Anchor Link

• One global DO for all users (hotspot)
• Storing large blobs in DO storage instead of R2
• Running multi-minute AI jobs inside the DO request path
• Using DOs when a simple KV counter with lossy increments would do

Deploy the counter firstCopy Anchor Link

1. Read Durable Objects get started
2. Open Durable Counter
3. Deploy and call increment a few times
4. Confirm consistent reads for the same object id
5. Open Chat Agent or DO SQLite Notes when you need a richer shape

You learn DO addressing and storage with the smallest useful API, then compose realtime or SQLite without rewriting the foundation - Workers as the vehicle, Durable Objects as the product capability.

Production checklistCopy Anchor Link

1. Design ID scheme first (idFromName is forever for that name).
2. Keep DO handlers short; offload heavy work to Queues.
3. Use transactions for multi-key updates (storage API).
4. Prefer SQLite in DOs when you need relational queries per entity.
5. Load-test hot IDs - one global DO is an anti-pattern.
6. Plan alarms for cleanup (alarms).

FAQCopy Anchor Link

DO vs D1?Copy Anchor Link

D1 is shared SQL across requests. A Durable Object is a sticky single-threaded entity. Use D1 for catalogs; DOs for rooms, sessions, and locks.

Can I put blobs in DO storage?Copy Anchor Link

Small state yes; large files belong in R2.