cloudflare-durable-objects

# Cloudflare Durable Objects

**Status**: Production Ready ✅
**Last Updated**: 2025-11-25
**Dependencies**: cloudflare-worker-base (recommended)
**Latest Versions**: wrangler@4.50.0+, @cloudflare/workers-types@4.20251125.0+
**Official Docs**: https://developers.cloudflare.com/durable-objects/

## Table of Contents
[What are Durable Objects?](#what-are-durable-objects) • [Quick Start](#quick-start-10-minutes) • [When to Load References](#when-to-load-references) • [Class Structure](#durable-object-class-structure) • [State API](#state-api---persistent-storage) • [WebSocket Hibernation](#websocket-hibernation-api) • [Alarms](#alarms-api---scheduled-tasks) • [RPC vs HTTP](#rpc-vs-http-fetch) • [Stubs & Routing](#creating-durable-object-stubs-and-routing) • [Migrations](#migrations---managing-do-classes) • [Common Patterns](#common-patterns) • [Critical Rules](#critical-rules) • [Known Issues](#known-issues-prevention)
## What are Durable Objects?

**Globally unique, stateful objects** with single-point coordination, strong consistency (ACID), WebSocket Hibernation (thousands of connections), SQLite storage (1GB), and alarms API.

**Use for:** Chat rooms, multiplayer games, rate limiting, session management, leader election, stateful workflows
---
## Quick Start (10 Minutes)

### Option 1: Scaffold New DO Project

```bash
npm create cloudflare@latest my-durable-app -- \
  --template=cloudflare/durable-objects-template --ts --git --deploy false
cd my-durable-app && bun install && npm run dev
```

### Option 2: Add to Existing Worker

**1. Install types:**
```bash
bun add -d @cloudflare/workers-types
```

**2. Create DO class** (`src/counter.ts`):
```typescript
import { DurableObject } from 'cloudflare:workers';

export class Counter extends DurableObject {
  async increment(): Promise<number> {
    let value: number = (await this.ctx.storage.get('value')) || 0;
    await this.ctx.storage.put('value', ++value);
    return value;
  }
}

export default Counter;  // CRITICAL
```

**3. Configure** (`wrangler.jsonc`):
```jsonc
{
  "durable_objects": {
    "bindings": [{ "name": "COUNTER", "class_name": "Counter" }]
  },
  "migrations": [
    { "tag": "v1", "new_sqlite_classes": ["Counter"] }
  ]
}
```

**4. Call from Worker** (`src/index.ts`):
```typescript
import { Counter } from './counter';

interface Env {
  COUNTER: DurableObjectNamespace<Counter>;
}

export { Counter };

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const stub = env.COUNTER.getByName('global-counter');
    return new Response(`Count: ${await stub.increment()}`);
  },
};
```

**Deploy:**

```bash
bunx wrangler deploy
```

---

## Available Commands

Use these interactive commands for guided workflows:

- **`/do-setup`** - Initialize new DO project with interactive setup wizard
  - Choose storage backend (SQL, KV, both)
  - Select use case pattern (WebSocket, Sessions, Rate Limiting, etc.)
  - Optional Vitest testing setup
  - Generates complete DO implementation

- **`/do-migrate`** - Interactive migration assistant
  - New class creation (new_sqlite_classes, new_classes)
  - Rename existing classes (renamed_classes)
  - Delete classes with safety confirmations (deleted_classes)
  - Transfer classes between scripts (transferred_classes)
  - Auto-increments migration tags (v1, v2, v3...)

- **`/do-debug`** - Step-by-step debugging workflow
  - Detects error categories (deployment, runtime, performance, etc.)
  - Runs diagnostic checks on configuration and code
  - Provides specific fixes with code examples
  - Guides local testing and production verification

- **`/do-patterns`** - Pattern selection wizard
  - Recommends DO pattern based on use case
  - Supports WebSocket, Rate Limiting, Sessions, Analytics, Leader Election
  - Generates complete pattern implementation
  - Provides best practices and optimization tips

- **`/do-optimize`** - Performance optimization assistant
  - Analyzes existing DO code for bottlenecks
  - Provides targeted optimization recommendations
  - Covers constructor, queries, WebSocket, memory, alarms
  - Measures performance improvements

## Autonomous Agents

These agents work autonomously without user interaction:

- **`do-debugger`** - Automatic error detection and fixing
  - Validates wrangler.jsonc configuration
  - Detects 16+ common DO errors
  - Applies fixes automatically with backups
  - Tests fixes before reporting

- **`do-setup-assistant`** - Automatic project scaffolding
  - Analyzes user requirements from natural language
  - Generates complete DO implementation
  - Creates tests, documentation, validation
  - Supports all use case patterns

- **`do-pattern-implementer`** - Production pattern implementation
  - Analyzes existing DO code
  - Recommends patterns by priority
  - Implements TTL cleanup, RPC metadata, SQL indexes, etc.
  - Generates pattern-specific tests

---

## When to Load References

**Load immediately when user mentions:**
- **`state-api-reference.md`** → "storage", "sql", "database", "query", "get/put", "KV", "1GB limit"
- **`websocket-hibernation.md`** → "websocket", "real-time", "chat", "hibernation", "serializeAttachment"
- **`alarms-api.md`** → "alarms", "scheduled tasks", "cron", "periodic", "batch processing"
- **`rpc-patterns.md`** → "RPC", "fetch", "HTTP", "methods", "routing"
- **`rpc-metadata.md`** → "RpcTarget", "metadata", "DO name", "idFromName access"
- **`stubs-routing.md`** → "stubs", "idFromName", "newUniqueId", "location hints", "jurisdiction"
- **`migrations-guide.md`** → "migrations", "rename", "delete", "transfer", "schema changes"
- **`migration-cheatsheet.md`** → "migration quick reference", "migration types", "common migrations"
- **`common-patterns.md`** → "patterns", "examples", "rate limiting", "sessions", "leader election"
- **`vitest-testing.md`** → "test", "testing", "vitest", "unit test", "@cloudflare/vitest-pool-workers"
- **`gradual-deployments.md`** → "gradual", "deployment", "traffic split", "r