Durable Objects — Cloudflare Demo Shop

What is the challenge?

How do you build real-time, stateful systems on a stateless platform?

Serverless functions are stateless by design — every request might land on a different instance. That works great for HTTP APIs but breaks down the moment you need to coordinate state: a chat room with 50 users, a multiplayer game lobby, a real-time document editor, per-tenant rate limiters, a queue with strict ordering. The usual answer is 'put a Redis cluster in front and deal with the connection management.' That's a lot of moving parts.

Architecture

How it fits together

Diagram coming soon

Architecture diagram for this solution will be added here.

Cloudflare's Solution

How Cloudflare solves it

One instance per object, globally. Each Durable Object is a single instance globally — addressed by ID. All requests to that ID go to the same instance, so state is locally consistent without distributed-locking. Cloudflare migrates instances to where the traffic is.
Built-in SQLite storage. Each DO has a transactional SQLite database persistent across restarts. Sub-millisecond queries from inside the Object. No external database needed for per-tenant state.
WebSockets and hibernation. Native WebSocket support with hibernation — your DO can hold thousands of WebSocket connections without consuming CPU. Pay only when work actually happens, even for sites that need persistent connections.
Alarms for scheduled work. Schedule a DO to wake up at a future time. Cron-per-object: 'remind users 24h before their event,' 'cleanup stale game lobbies every 5min,' 'flush metrics buffer hourly.' All inside the same DO instance.
Sharded by you, not by cluster ops. Want one DO per chat room? One per user? One per game? Pick your own sharding key. No re-sharding event when you scale — each ID is automatically routed to its own instance.

FAQ

Common questions

When should I use a Durable Object vs. D1 or KV?

D1 for relational queries across many users. KV for global read-heavy data. Durable Objects for single-writer-per-key consistency, real-time coordination, or stateful per-entity logic. A chat room is a DO; the list of all chat rooms is in D1; the read-only assets are in KV/R2.

What's the difference between a DO and a Worker?

A Worker is stateless and runs anywhere globally on any node. A DO is stateful — one instance per ID, with attached storage. Workers handle the high-volume request layer; DOs handle the stateful coordination layer. They work together: a Worker receives the request, finds the right DO, and forwards.

How does DO billing work?

Per request (similar to Workers) plus per-millisecond of active CPU. WebSocket hibernation means you don't pay for idle connections. Storage is billed per GB-month. For most use cases, DOs cost a fraction of what a managed Redis or DynamoDB cluster would.

Where does my DO run?

Cloudflare locates each DO instance close to where its traffic comes from, and migrates it if traffic patterns shift. You don't pick a region — the platform handles it.

Let's Test!

Try it live

Open this page in two browser tabs to see real-time sync. Each tab is a separate user; the room is one shared Durable Object instance. Messages are screened by Llama Guard 3 (Workers AI) to keep the room PG.

One Durable Object instance backs this room. Open this page in a second tab (or send it to a colleague) — pick a username in each, and watch messages sync live. Every tab is a different user; the room is shared. This is a PG room: every message is screened by Llama Guard 3 on Workers AI before it's stored — violent, hateful, or explicit content is blocked.

Pick a username to join

Chatting as

No messages yet. Say hello.

Daily reset in (17:00 UTC, via a Durable Object alarm)

Dive Deeper

Docs & blogs

Documentation

Blogs

← Back to all solutions