Building Stateful Applications with Cloudflare Durable Objects

Durable Objects are Cloudflare's solution for stateful compute at the edge—single-instance JavaScript classes that maintain state across requests and coordinate real-time behavior. They solve a fundamental limitation of stateless Workers.

The Stateless Edge Problem

Cloudflare Workers are stateless by design. Each request may be handled by a different data center. While KV and D1 provide persistent storage, they add latency for coordination-heavy workloads. WebSocket rooms, distributed rate limiting, and atomic counters require a coordination primitive that external databases cannot provide efficiently.

How Durable Objects Work

A Durable Object is identified by a unique name. All HTTP requests and WebSocket connections for that name route to the same single instance running in one data center. This gives you a coordination primitive: a JavaScript class that maintains in-memory state, processes messages in order, and persists state to disk.

The key property is global uniqueness. Whether you have one user or one million, there is exactly one instance handling requests for a given ID. This eliminates race conditions naturally.

Practical Patterns

Real-Time Presence

Create one Durable Object per chat room or collaboration session. Each WebSocket connection registers with the DO. When a user connects or disconnects, the DO broadcasts the updated participant list. No external database needed.

Distributed Rate Limiting

Use one DO per user or API key. All requests for that key route to the same DO, which maintains an accurate request count with no race conditions. Compare this to KV-based rate limiting, where concurrent requests can all read the same stale count.

Atomic Counters

Visitor counts, vote tallies, and resource usage metrics need atomic increments. A Durable Object provides a single source of truth without the eventual consistency issues of distributed counters.

Deployment Considerations

Durable Objects use wall-clock time for setTimer and alarm. Be aware of potential clock drift across data centers. Always implement idempotency in your message handlers since at-least-once delivery means duplicate messages are possible. Design your state schema to handle re-entrant calls.

Cost Model

Durable Objects are billed by duration (per-million-milliseconds) plus request count. They are more expensive than stateless Workers but significantly cheaper than maintaining your own stateful infrastructure across regions.