durable-objects

Name: durable-objects
Author: cloudflare

bycloudflare· 64 skills

Installs

30k

Stars

2.5k

Forks

232

How to install durable-objects?

cloudflare/skills/durable-objects

$npx -y skills add cloudflare/skills --skill durable-objects

Installs into the current project.

›Prefer a prompt? Paste this to your agent

Use this skill

Run `npx skills use "https://github.com/cloudflare/skills" --skill "cloudflare/skills/durable-objects"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the whole pack

Use the skills in "https://github.com/cloudflare/skills" that are relevant to the current task. Run `npx skills add "https://github.com/cloudflare/skills"` and select the relevant skills, then follow their instructions.

Files · 1

View on GitHub

SKILL.md

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

6 picks

Type

Run `npx skills use "https://github.com/cloudflare/skills" --skill "cloudflare/skills/durable-objects"` and follow the generated skill instructions now. Read its complete output, redirecting it to a temporary file first if necessary. Resolve relative paths from the supporting-files directory it provides.

Use the skills in "https://github.com/cloudflare/skills" that are relevant to the current task. Run `npx skills add "https://github.com/cloudflare/skills"` and select the relevant skills, then follow their instructions.

durable-objects

How to install durable-objects?

Related

durable-objects

How to install durable-objects?

Related