OpenSkillIndex← back to search
claude-code

Claude-skills cloudflare-workers-dev-experience

Cloudflare Workers local development with Wrangler, Miniflare, hot reload, debugging. Use for project setup, wrangler.jsonc configuration, or encountering local dev, HMR, binding simulation errors.

install
source · Clone the upstream repo
git clone https://github.com/secondsky/claude-skills
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/secondsky/claude-skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/plugins/cloudflare-workers/skills/cloudflare-workers-dev-experience" ~/.claude/skills/secondsky-claude-skills-cloudflare-workers-dev-experience && rm -rf "$T"
manifest: plugins/cloudflare-workers/skills/cloudflare-workers-dev-experience/SKILL.md
source content

Cloudflare Workers Developer Experience

Local development setup with Wrangler, Miniflare, and modern tooling.

Quick Start

# Create new project
bunx create-cloudflare@latest my-worker

# Or from scratch
mkdir my-worker && cd my-worker
bun init -y
bun add -d wrangler @cloudflare/workers-types

# Start local development
bunx wrangler dev

Essential wrangler.jsonc

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2024-12-01",

  // Development settings
  "dev": {
    "port": 8787,
    "local_protocol": "http"
  },

  // Environment variables (non-secret)
  "vars": {
    "ENVIRONMENT": "development"
  },

  // Bindings
  "kv_namespaces": [
    { "binding": "KV", "id": "abc123", "preview_id": "def456" }
  ],

  "d1_databases": [
    { "binding": "DB", "database_id": "xyz789", "database_name": "my-db" }
  ],

  "r2_buckets": [
    { "binding": "BUCKET", "bucket_name": "my-bucket" }
  ]
}

Critical Rules

  1. Always use 
    wrangler dev
    for local testing     - Simulates Cloudflare runtime accurately
  2. Set 
    compatibility_date
     - Controls runtime behavior, update quarterly
  3. Use preview IDs for local dev - Separate from production bindings
  4. Configure TypeScript properly - Use 
    @cloudflare/workers-types
  5. Enable source maps - Better error stacks in development

Top 6 Errors Prevented

ErrorSymptomPrevention
Module not foundImport errors on deploySet 
"moduleResolution": "bundler"
in tsconfig
Binding undefined
env.KV is undefined
locally		Add 
preview_id
to KV namespace config
HMR not workingChanges not reflectingCheck port conflicts, use 
--local
flag
D1 schema mismatchQueries fail locallyRun migrations on local DB
Type errorsMissing binding typesGenerate types with 
wrangler types
CORS issuesBrowser blocking requestsAdd CORS headers in dev handler

Local Development Workflow

# Start dev server (recommended)
bunx wrangler dev

# With live reload
bunx wrangler dev --live-reload

# Remote mode (use actual Cloudflare services)
bunx wrangler dev --remote

# Specify environment
bunx wrangler dev --env staging

# Custom port
bunx wrangler dev --port 3000

TypeScript Configuration

tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "lib": ["ES2022"],
    "types": ["@cloudflare/workers-types"],
    "strict": true,
    "noEmit": true,
    "skipLibCheck": true,
    "allowSyntheticDefaultImports": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

Package.json Scripts

{
  "scripts": {
    "dev": "wrangler dev",
    "deploy": "wrangler deploy",
    "deploy:staging": "wrangler deploy --env staging",
    "deploy:production": "wrangler deploy --env production",
    "test": "vitest",
    "test:watch": "vitest --watch",
    "type-check": "tsc --noEmit",
    "lint": "eslint src/",
    "types": "wrangler types",
    "tail": "wrangler tail",
    "db:migrate": "wrangler d1 migrations apply DB",
    "db:studio": "wrangler d1 execute DB --local --command 'SELECT 1'"
  }
}

Debugging

Console Logging

// Development-only logging
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    if (env.ENVIRONMENT === 'development') {
      console.log('Request:', request.method, request.url);
      console.log('Headers:', Object.fromEntries(request.headers));
    }

    // Handler logic...
  }
};

Using wrangler tail

# Real-time logs from deployed worker
wrangler tail

# Filter by status
wrangler tail --status error

# Filter by method
wrangler tail --method POST

# JSON format for parsing
wrangler tail --format json

VS Code Debugging

.vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Wrangler Dev",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "bunx",
      "runtimeArgs": ["wrangler", "dev", "--inspector-port", "9229"],
      "skipFiles": ["<node_internals>/**"],
      "sourceMaps": true
    }
  ]
}

When to Load References

Load specific references based on the task:

  • Setting up project? → Load 
    references/local-development.md
    for complete setup guide
  • Configuring wrangler? → Load 
    references/wrangler-config.md
    for all configuration options
  • Debugging issues? → Load 
    references/debugging-tools.md
    for debugging techniques

Templates

TemplatePurposeUse When
templates/wrangler-config.jsonc
Complete wrangler configStarting new project
templates/dev-script.ts
Development utilitiesAdding dev helpers

Scripts

ScriptPurposeCommand
scripts/dev-setup.sh
Initialize dev environment
./dev-setup.sh

Resources