Use for: Chat rooms, multiplayer games, rate limiting, session management, leader election, stateful 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

• 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

• 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", "rollout", "canary"

• typescript-config.md

  → "TypeScript", "types", "tsconfig", "wrangler.jsonc", "bindings"

• advanced-sql-patterns.md

  → "CTE", "window functions", "FTS5", "full-text search", "JSON functions", "complex SQL"

• security-best-practices.md

  → "security", "authentication", "authorization", "SQL injection", "CORS", "encryption", "rate limiting"

• error-codes.md

  → "error codes", "error catalog", "specific error", "E001", "troubleshooting"

• top-errors.md

  → errors, "not working", debugging, "binding not found"

• Building new feature → Load relevant pattern from

  common-patterns.md

• Debugging issue → Load

  error-codes.md

  for specific errors, then

  top-errors.md

• Implementing WebSocket → Load

  websocket-hibernation.md

  before coding
• Setting up storage → Load

  state-api-reference.md

  for SQL/KV APIs
• Complex SQL queries → Load

  advanced-sql-patterns.md

  for CTEs, window functions, FTS5
• Security review → Load

  security-best-practices.md

  for authentication, authorization, SQL injection prevention
• Creating first DO → Load

  stubs-routing.md

  for ID methods
• Writing tests → Load

  vitest-testing.md

  for testing patterns
• Planning deployment → Load

  gradual-deployments.md

  for rollout strategy
• Migration needed → Load

  migration-cheatsheet.md

  for quick reference
• Using DO name inside DO → Load

  rpc-metadata.md

  for RpcTarget pattern
• TypeScript configuration → Load

  typescript-config.md

  for setup

• Access via

  ctx.storage.sql

• Up to 1GB storage per instance
• SQL queries with transactions, indexes, cursors
• Atomic operations (deleteAll is all-or-nothing)
• Use

  new_sqlite_classes

  in migrations

• Access via

  ctx.storage

  (get/put/delete/list)
• Simple key-value operations
• Async transactions supported
• 128MB limit on KV backend, 1GB on SQLite

export class Counter extends DurableObject {
  sql: SqlStorage;

  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    this.sql = ctx.storage.sql;
    this.sql.exec('CREATE TABLE IF NOT EXISTS counts (key TEXT PRIMARY KEY, value INTEGER)');
  }

  async increment(): Promise<number> {
    this.sql.exec('INSERT OR REPLACE INTO counts (key, value) VALUES (?, ?)', 'count', 1);
    return this.sql.exec('SELECT value FROM counts WHERE key = ?', 'count').one<{value: number}>().value;
  }
}

references/state-api-reference.md

• ✅ Use

  ctx.acceptWebSocket(server)

  (enables hibernation)
• ✅ Use

  ws.serializeAttachment(data)

  to persist metadata across hibernation
• ✅ Restore connections in constructor with

  ctx.getWebSockets()

• ❌ Don't use

  ws.accept()

  (standard API, no hibernation)
• ❌ Don't use

  setTimeout

  /

  setInterval

  (prevents hibernation)

webSocketMessage()

webSocketClose()

webSocketError()

export class ChatRoom extends DurableObject {
  sessions: Map<WebSocket, any>;

  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    this.sessions = new Map();
    // Restore connections after hibernation
    ctx.getWebSockets().forEach(ws => {
      this.sessions.set(ws, ws.deserializeAttachment());
    });
  }

  async fetch(request: Request): Promise<Response> {
    const pair = new WebSocketPair();
    const [client, server] = Object.values(pair);

    this.ctx.acceptWebSocket(server);  // ← Enables hibernation
    server.serializeAttachment({ userId: 'alice' });  // ← Persists across hibernation
    this.sessions.set(server, { userId: 'alice' });

    return new Response(null, { status: 101, webSocket: client });
  }

  async webSocketMessage(ws: WebSocket, message: string): Promise<void> {
    const session = this.sessions.get(ws);
    // Broadcast to all
    this.sessions.forEach((_, w) => w.send(message));
  }
}

references/websocket-hibernation.md

• await ctx.storage.setAlarm(timestamp)

  - Schedule alarm

• await ctx.storage.getAlarm()

  - Get current alarm time (null if not set)

• await ctx.storage.deleteAlarm()

  - Cancel alarm

• async alarm(info)

  - Handler called when alarm fires

• ✅ Guaranteed at-least-once execution with automatic retries (up to 6)
• ✅ Survives hibernation and eviction
• ✅ Deleted automatically after successful execution
• ⚠️ Only ONE alarm per DO (setting new one overwrites previous)

export class Batcher extends DurableObject {
  async addItem(item: string): Promise<void> {
    await this.ctx.storage.put('items', [...existingItems, item]);

    // Schedule batch processing if not already scheduled
    if (await this.ctx.storage.getAlarm() === null) {
      await this.ctx.storage.setAlarm(Date.now() + 10000);  // 10 seconds
    }
  }

  async alarm(info: { retryCount: number; isRetry: boolean }): Promise<void> {
    const items = await this.ctx.storage.get('items');
    await this.processBatch(items);  // Send to API, write to DB, etc.
    await this.ctx.storage.put('items', []);  // Clear buffer
  }
}

references/alarms-api.md

1. idFromName(name)

   - Named DOs (most common): Deterministic routing to same instance globally

2. newUniqueId()

   - Random IDs: New unique instance, must store ID for future access

3. idFromString(idString)

   - Recreate from saved ID string

// Method 1: From ID
const id = env.CHAT_ROOM.idFromName('room-123');
const stub = env.CHAT_ROOM.get(id);

// Method 2: Shortcut for named DOs (recommended)
const stub = env.CHAT_ROOM.getByName('room-123');

await stub.myMethod();

• Set

  locationHint

  option when creating stub:

  { locationHint: 'enam' }

• 9 regions: wnam, enam, sam, weur, eeur, apac, oc, afr, me
• Best-effort (not guaranteed), only affects first creation

• Use

  newUniqueId({ jurisdiction: 'eu' })

  or

  { jurisdiction: 'fedramp' }

• Strictly enforced (DO never leaves jurisdiction)
• Cannot combine with location hints
• Required for GDPR/FedRAMP compliance

references/stubs-routing.md

1. Create New DO: Use

   new_sqlite_classes

   (recommended, 1GB) or

   new_classes

   (legacy KV, 128MB)
2. Rename DO: Use

   renamed_classes

   with

   from

   /

   to

   mapping (data preserved, bindings forward)
3. Delete DO: Use

   deleted_classes

   (⚠️ immediate deletion, cannot undo, all storage lost)
4. Transfer DO: Use

   transferred_classes

   with

   from_script

   (moves instances to new Worker)

{
  "durable_objects": {
    "bindings": [{ "name": "COUNTER", "class_name": "Counter" }]
  },
  "migrations": [
    {
      "tag": "v1",                    // Unique identifier (append-only)
      "new_sqlite_classes": ["Counter"]
    }
  ]
}

• ❌ Migrations are ATOMIC (all instances migrate at once, no gradual rollout)
• ❌ Cannot enable SQLite on existing KV-backed DOs (must create new class)
• ❌ Migration tags must be unique (cannot reuse, append-only)
• ✅ Code changes don't need migrations (only schema changes do)
• ✅ DO class names are unique per account (across all Workers)

references/migrations-guide.md

1. Rate Limiting - Per-user rate limiting with sliding window, KV storage for request tracking
2. Session Management - User sessions with TTL, SQL storage, automatic cleanup via alarms
3. Leader Election - Single leader guarantee using SQL constraints, heartbeat mechanism
4. Multi-DO Coordination - Game coordinator + game rooms pattern, parent-child DO relationships

export class RateLimiter extends DurableObject {
  async checkLimit(userId: string, limit: number, window: number): Promise<boolean> {
    const requests = await this.ctx.storage.get<number[]>(`rate:${userId}`) || [];
    const validRequests = requests.filter(t => Date.now() - t < window);

    if (validRequests.length >= limit) return false;

    validRequests.push(Date.now());
    await this.ctx.storage.put(`rate:${userId}`, validRequests);
    return true;
  }
}

references/common-patterns.md

• Export DO class:

  export default MyDO

• Call

  super(ctx, env)

  first in constructor
• Use

  new_sqlite_classes

  in migrations (1GB vs 128MB KV)
• Use

  ctx.acceptWebSocket()

  for hibernation (not

  ws.accept()

  )
• Persist state to storage (not just memory)
• Use alarms instead of setTimeout/setInterval
• Use parameterized SQL:

  sql.exec('... WHERE id = ?', id)

• Minimize constructor work, use

  blockConcurrencyWhile()

• Create DO without migration (error)
• Forget to export class (binding not found)
• Use setTimeout/setInterval (prevents hibernation)
• Rely only on in-memory state for WebSockets (use serializeAttachment)
• Deploy migrations gradually (migrations are atomic)
• Enable SQLite on existing KV-backed DO (must create new class)
• Assume location hints are guaranteed (best-effort only)

references/typescript-config.md

• State API (SQL): https://developers.cloudflare.com/durable-objects/api/sqlite-storage-api/
• WebSocket Hibernation: https://developers.cloudflare.com/durable-objects/best-practices/websockets/
• Alarms API: https://developers.cloudflare.com/durable-objects/api/alarms/
• Migrations: https://developers.cloudflare.com/durable-objects/reference/durable-objects-migrations/
• Best Practices: https://developers.cloudflare.com/durable-objects/best-practices/ Questions? Load

  references/top-errors.md

  for common problems or check

  templates/

  for working examples