/do-setup

name: cloudflare-durable-objects:setup
description: Interactive Durable Objects project initialization. Scaffolds new DO project with proper bindings, migrations, and boilerplate code.

Durable Objects Setup Command

Interactive command to initialize a new Durable Objects project with proper configuration, bindings, migrations, and boilerplate code.

Overview

This command guides through the complete setup process for Cloudflare Durable Objects, ensuring correct configuration from the start. It handles:

• Project scaffolding (new or existing project)
• Durable Object class creation with proper exports
• wrangler.jsonc configuration (bindings, migrations)
• TypeScript setup and type definitions
• Test environment setup (optional Vitest)
• Template selection (basic, WebSocket, SQL storage)

Step 1: Gather Project Requirements

Use AskUserQuestion tool to collect setup preferences:

Question 1: Project Type

**Question**: "Are you setting up a new project or adding Durable Objects to an existing project?" **Header**: "Project Type" **Options**:

• **New Project** - Create new Cloudflare Workers project with Durable Objects
• Description: "Scaffold a complete new project using `npm create cloudflare@latest`"
• **Existing Project** - Add Durable Objects to existing Workers project
• Description: "Configure Durable Objects in an existing wrangler.jsonc"

Question 2: Storage Backend

**Question**: "Which storage backend do you want to use for your Durable Object?" **Header**: "Storage Backend" **Options**:

• **SQL Storage (Recommended)** - SQLite with 1GB limit per DO instance
• Description: "Structured data with ACID transactions, recommended for most use cases"
• **Key-Value Storage** - Simple KV storage with 128MB limit
• Description: "Simpler API, good for basic state management"
• **Both SQL + KV** - Use both storage backends
• Description: "SQL for structured data, KV for simple key-value pairs"

Question 3: Use Case Pattern

**Question**: "What will your Durable Object primarily be used for?" **Header**: "Use Case" **Options**:

• **WebSocket Chat/Real-time** - WebSocket server with hibernation
• Description: "Chat rooms, collaborative editing, multiplayer games"
• **Session Management** - Per-user session storage
• Description: "User sessions, authentication state, preferences"
• **Rate Limiting** - Request rate limiting per user/IP
• Description: "API rate limiting, DDoS protection"
• **Data Aggregation** - Collect and aggregate data
• Description: "Analytics, metrics collection, data pipelines"
• **Custom/Other** - General-purpose Durable Object
• Description: "Start with basic template and customize"

Question 4: Testing Setup

**Question**: "Do you want to set up Vitest for testing your Durable Objects?" **Header**: "Testing" **Options**:

• **Yes (Recommended)** - Install and configure Vitest with @cloudflare/vitest-pool-workers
• Description: "Enables unit testing with isolated DO storage"
• **No** - Skip test setup
• Description: "Can add testing later if needed"

Step 2: Validate Environment

Before proceeding with setup, validate the development environment:

Check Prerequisites

Run validation checks:

# Check Node.js version (18+ required)
node --version

# Check if wrangler is installed
wrangler --version

# Check if in valid directory
pwd

Validation Logic

If **New Project**:

• Verify not inside existing Node project (no package.json)
• Check directory is empty or confirm overwrite

If **Existing Project**:

• Verify package.json exists
• Verify wrangler.jsonc exists
• Check for existing DO bindings (warn if found)

Installation Commands

If wrangler not installed:

npm install -g wrangler@latest

If wrong Node.js version:

# Recommend using nvm to install Node 20+
nvm install 20
nvm use 18

Step 3: Project Scaffolding

Execute setup based on user selections:

For New Project

Run npm create cloudflare:

npm create cloudflare@latest my-durable-objects-app -- \
  --template=cloudflare/durable-objects-template \
  --ts --git --deploy false

cd my-durable-objects-app

For Existing Project

No scaffolding needed, proceed to configuration.

Step 4: Create Durable Object Class

Generate DO class file based on selected use case pattern:

Determine File Path

• Check if `src/` directory exists, otherwise create it
• Create DO class file: `src/DurableObject.ts` (or custom name from user)

Generate Class Code

Based on **Use Case Pattern** selection:

WebSocket Chat/Real-time Pattern

import { DurableObject } from "cloudflare:workers";

export class ChatRoom extends DurableObject {
  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);

    this.ctx.blockConcurrencyWhile(async () => {
      // Initialize SQL schema for message history
      if (STORAGE_BACKEND includes "SQL") {
        await this.ctx.storage.sql.exec(`
          CREATE TABLE IF NOT EXISTS messages (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            user_id TEXT NOT NULL,
            message TEXT NOT NULL,
            timestamp INTEGER NOT NULL
          )
        `);
      }
    });
  }

  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url);

    // WebSocket upgrade
    if (request.headers.get("Upgrade") === "websocket") {
      const pair = new WebSocketPair();
      this.ctx.acceptWebSocket(pair[0]);
      return new Response(null, { status: 101, webSocket: pair[1] });
    }

    return new Response("WebSocket endpoint", { status: 200 });
  }

  async webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): Promise<void> {
    // Broadcast to all connected clients
    const websockets = this.ctx.getWebSockets();
    websockets.forEach((client) => {
      client.send(message);
    });

    // Store message in SQL (if enabled)
    if (STORAGE_BACKEND includes "SQL") {
      const data = typeof mes