Durable Objects

1---
2name: durable-objects
3description: Create and review Cloudflare Durable Objects. Use when building stateful coordination (chat rooms, multiplayer games, booking systems), implementing RPC methods, SQLite storage, alarms, WebSockets, or reviewing DO code for best practices. Covers Workers integration, wrangler config, and testing with Vitest.
4---
5 
6# Durable Objects
7 
8Build stateful, coordinated applications on Cloudflare's edge using Durable Objects.
9 
10## Retrieval-First Development
11 
12**Prefer retrieval from official docs over pre-training for Durable Objects tasks.**
13 
14| Resource | URL |
15|----------|-----|
16| Docs | https://developers.cloudflare.com/durable-objects/ |
17| API Reference | https://developers.cloudflare.com/durable-objects/api/ |
18| Best Practices | https://developers.cloudflare.com/durable-objects/best-practices/ |
19| Examples | https://developers.cloudflare.com/durable-objects/examples/ |
20 
21Fetch the relevant doc page when implementing features.
22 
23## When to Use
24 
25- Creating new Durable Object classes for stateful coordination
26- Implementing RPC methods, alarms, or WebSocket handlers
27- Reviewing existing DO code for best practices
28- Configuring wrangler.jsonc/toml for DO bindings and migrations
29- Writing tests with `@cloudflare/vitest-pool-workers`
30- Designing sharding strategies and parent-child relationships
31 
32## Reference Documentation
33 
34- `./references/rules.md` - Core rules, storage, concurrency, RPC, alarms
35- `./references/testing.md` - Vitest setup, unit/integration tests, alarm testing
36- `./references/workers.md` - Workers handlers, types, wrangler config, observability
37 
38Search: `blockConcurrencyWhile`, `idFromName`, `getByName`, `setAlarm`, `sql.exec`
39 
40## Core Principles
41 
42### Use Durable Objects For
43 
44| Need | Example |
45|------|---------|
46| Coordination | Chat rooms, multiplayer games, collaborative docs |
47| Strong consistency | Inventory, booking systems, turn-based games |
48| Per-entity storage | Multi-tenant SaaS, per-user data |
49| Persistent connections | WebSockets, real-time notifications |
50| Scheduled work per entity | Subscription renewals, game timeouts |
51 
52### Do NOT Use For
53 
54- Stateless request handling (use plain Workers)
55- Maximum global distribution needs
56- High fan-out independent requests
57 
58## Quick Reference
59 
60### Wrangler Configuration
61 
62```jsonc
63// wrangler.jsonc
64{
65  "durable_objects": {
66    "bindings": [{ "name": "MY_DO", "class_name": "MyDurableObject" }]
67  },
68  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyDurableObject"] }]
69}
70```
71 
72### Basic Durable Object Pattern
73 
74```typescript
75import { DurableObject } from "cloudflare:workers";
76 
77export interface Env {
78  MY_DO: DurableObjectNamespace<MyDurableObject>;
79}
80 
81export class MyDurableObject extends DurableObject<Env> {
82  constructor(ctx: DurableObjectState, env: Env) {
83    super(ctx, env);
84    ctx.blockConcurrencyWhile(async () => {
85      this.ctx.storage.sql.exec(`
86        CREATE TABLE IF NOT EXISTS items (
87          id INTEGER PRIMARY KEY AUTOINCREMENT,
88          data TEXT NOT NULL
89        )
90      `);
91    });
92  }
93 
94  async addItem(data: string): Promise<number> {
95    const result = this.ctx.storage.sql.exec<{ id: number }>(
96      "INSERT INTO items (data) VALUES (?) RETURNING id",
97      data
98    );
99    return result.one().id;
100  }
101}
102 
103export default {
104  async fetch(request: Request, env: Env): Promise<Response> {
105    const stub = env.MY_DO.getByName("my-instance");
106    const id = await stub.addItem("hello");
107    return Response.json({ id });
108  },
109};
110```
111 
112## Critical Rules
113 
1141. **Model around coordination atoms** - One DO per chat room/game/user, not one global DO
1152. **Use `getByName()` for deterministic routing** - Same input = same DO instance
1163. **Use SQLite storage** - Configure `new_sqlite_classes` in migrations
1174. **Initialize in constructor** - Use `blockConcurrencyWhile()` for schema setup only
1185. **Use RPC methods** - Not fetch() handler (compatibility date >= 2024-04-03)
1196. **Persist first, cache second** - Always write to storage before updating in-memory state
1207. **One alarm per DO** - `setAlarm()` replaces any existing alarm
121 
122## Anti-Patterns (NEVER)
123 
124- Single global DO handling all requests (bottleneck)
125- Using `blockConcurrencyWhile()` on every request (kills throughput)
126- Storing critical state only in memory (lost on eviction/crash)
127- Using `await` between related storage writes (breaks atomicity)
128- Holding `blockConcurrencyWhile()` across `fetch()` or external I/O
129 
130## Stub Creation
131 
132```typescript
133// Deterministic - preferred for most cases
134const stub = env.MY_DO.getByName("room-123");
135 
136// From existing ID string
137const id = env.MY_DO.idFromString(storedIdString);
138const stub = env.MY_DO.get(id);
139 
140// New unique ID - store mapping externally
141const id = env.MY_DO.newUniqueId();
142const stub = env.MY_DO.get(id);
143```
144 
145## Storage Operations
146 
147```typescript
148// SQL (synchronous, recommended)
149this.ctx.storage.sql.exec("INSERT INTO t (c) VALUES (?)", value);
150const rows = this.ctx.storage.sql.exec<Row>("SELECT * FROM t").toArray();
151 
152// KV (async)
153await this.ctx.storage.put("key", value);
154const val = await this.ctx.storage.get<Type>("key");
155```
156 
157## Alarms
158 
159```typescript
160// Schedule (replaces existing)
161await this.ctx.storage.setAlarm(Date.now() + 60_000);
162 
163// Handler
164async alarm(): Promise<void> {
165  // Process scheduled work
166  // Optionally reschedule: await this.ctx.storage.setAlarm(...)
167}
168 
169// Cancel
170await this.ctx.storage.deleteAlarm();
171```
172 
173## Testing Quick Start
174 
175```typescript
176import { env } from "cloudflare:test";
177import { describe, it, expect } from "vitest";
178 
179describe("MyDO", () => {
180  it("should work", async () => {
181    const stub = env.MY_DO.getByName("test");
182    const result = await stub.addItem("test");
183    expect(result).toBe(1);
184  });
185});
186```
187