# Install globally (npm or pnpm)
npm install -g wrangler
pnpm add -g wrangler

# Install as devDependency (recommended for projects — pins version)
npm install --save-dev wrangler
npx wrangler --version

# Check version
wrangler --version

# OAuth login (opens browser — best for local dev)
wrangler login

# Log out
wrangler logout

# Show authenticated account info
wrangler whoami

# Use API token instead of OAuth (CI/CD, automated pipelines)
export CLOUDFLARE_API_TOKEN=your_token_here
wrangler whoami   # validates token

# Required fields
name = "my-worker"                    # Worker name (unique per account)
main = "src/index.ts"                 # Entry point
compatibility_date = "2024-11-01"     # Locks behavior to a specific date
account_id = "abc123..."              # Your Cloudflare account ID

# Optional: target specific zones/routes
routes = [
  { pattern = "example.com/api/*", zone_name = "example.com" }
]

# Optional: custom domains (no route matching overhead)
[[routes]]
pattern = "api.example.com/*"
custom_domain = true

# Build configuration
[build]
command = "npm run build"
cwd = "."
watch_dir = "src"

# Node.js compatibility (for npm packages using Node APIs)
node_compat = true

# Compatibility flags (enables specific behaviors)
compatibility_flags = ["nodejs_compat", "streams_enable_constructors"]

# Workers Unbound (no 10ms CPU limit — billed per duration)
[limits]
cpu_ms = 30000

# Default environment (production)
name = "my-worker"
main = "src/index.ts"
compatibility_date = "2024-11-01"

[vars]
API_URL = "https://api.example.com"

# Staging environment
[env.staging]
name = "my-worker-staging"
vars = { API_URL = "https://staging-api.example.com" }
route = "staging.example.com/*"

# Preview environment
[env.preview]
name = "my-worker-preview"

# Deploy to staging
wrangler deploy --env staging

# Tail logs from staging
wrangler tail --env staging

# Run dev against staging bindings
wrangler dev --env staging --remote

# Create new Worker project (interactive)
wrangler init my-worker

# Non-interactive (no git, no tests)
wrangler init my-worker --no-delegate-c3

# Use Cloudflare's create-cloudflare CLI (recommended for full project scaffolding)
npm create cloudflare@latest my-worker

# Start local dev server (default: localhost:8787)
wrangler dev

# Specify port and IP
wrangler dev --port 3000 --ip 0.0.0.0

# Local mode — runs entirely locally via Miniflare (no Cloudflare network)
wrangler dev --local

# Remote mode — proxies to Cloudflare's edge (uses real bindings, real KV/D1)
wrangler dev --remote

# Test against staging environment
wrangler dev --env staging --remote

# Live reload on save (default: on)
wrangler dev --watch

# Expose local dev server publicly via quick tunnel
wrangler dev --local-protocol https

# Deploy to production
wrangler deploy

# Deploy specific environment
wrangler deploy --env staging

# Deploy without publishing (dry-run shows what would be deployed)
wrangler deploy --dry-run

# Deploy with specific compatibility date
wrangler deploy --compatibility-date 2024-11-01

# Force deploy even if no changes (re-deploys same code)
wrangler deploy --dispatch-namespace my-namespace

# Upload source maps (for better error traces in dashboard)
wrangler deploy --upload-source-maps

# Delete a Worker
wrangler delete

# Delete specific environment
wrangler delete --env staging

# Delete by name
wrangler delete --name my-worker

# Stream logs from production worker
wrangler tail

# Stream from specific environment
wrangler tail --env staging

# Output as JSON (for piping to jq or log aggregators)
wrangler tail --format json

# Filter by HTTP status code
wrangler tail --status 500
wrangler tail --status 200

# Filter by HTTP method
wrangler tail --method POST

# Filter by IP address
wrangler tail --ip 1.2.3.4

# Filter by search term in log body
wrangler tail --search "error"

# Combine filters
wrangler tail --status 500 --format json | jq '.exceptions[]'

# Set sampling rate (0-1, default 1 = 100%)
wrangler tail --sampling-rate 0.1

# List deployed versions
wrangler versions list

# View specific version
wrangler versions view <version-id>

# Rollback to previous version
wrangler rollback

# Rollback to specific version
wrangler rollback <version-id>

# Gradual rollout (versions traffic splitting)
wrangler versions upload           # Upload without deploying
wrangler deployments create        # Create deployment with traffic %

# KV Namespace binding
[[kv_namespaces]]
binding = "MY_KV"
id = "abc123..."
preview_id = "xyz789..."      # Used during wrangler dev

# R2 Bucket binding
[[r2_buckets]]
binding = "MY_BUCKET"
bucket_name = "my-bucket"
preview_bucket_name = "my-bucket-preview"

# D1 Database binding
[[d1_databases]]
binding = "MY_DB"
database_name = "my-database"
database_id = "abc123..."

# Durable Objects binding
[[durable_objects.bindings]]
name = "MY_DO"
class_name = "MyDurableObject"

# Service binding (call another Worker)
[[services]]
binding = "AUTH_SERVICE"
service = "auth-worker"
environment = "production"

# Queue Producer binding
[[queues.producers]]
binding = "MY_QUEUE"
queue = "my-queue"

# Queue Consumer
[[queues.consumers]]
queue = "my-queue"
max_batch_size = 10
max_batch_timeout = 5
max_retries = 3
dead_letter_queue = "my-dlq"

# Vectorize index
[[vectorize]]
binding = "MY_VECTORIZE"
index_name = "my-index"

# Workers AI
[ai]
binding = "AI"

# Hyperdrive (accelerated access to regional DBs)
[[hyperdrive]]
binding = "MY_HYPERDRIVE"
id = "abc123..."

# Route pattern (zone must be in your account)
[[routes]]
pattern = "example.com/api/*"
zone_name = "example.com"
# or zone_id = "abc123..."

# Custom domain (Workers takes over entire hostname)
[[routes]]
pattern = "api.example.com/*"
custom_domain = true

[triggers]
crons = ["0 * * * *", "*/5 * * * *"]   # Hourly + every 5 mins

// Worker handler
export default {
  scheduled(event: ScheduledEvent, env: Env, ctx: ExecutionContext) {
    ctx.waitUntil(doWork(env));
  }
};

# Create namespace
wrangler kv namespace create MY_KV

# Create preview namespace (for local dev)
wrangler kv namespace create MY_KV --preview

# List all namespaces
wrangler kv namespace list

# Delete namespace
wrangler kv namespace delete --namespace-id abc123

# Put a value
wrangler kv key put --namespace-id abc123 "user:123" '{"name":"Alice"}'

# Put with TTL (seconds, min 60)
wrangler kv key put --namespace-id abc123 "session:xyz" "token" --ttl 3600

# Put with expiration (Unix timestamp)
wrangler kv key put --namespace-id abc123 "cache:page" "<html>" --expiration 1735689600

# Put with metadata
wrangler kv key put --namespace-id abc123 "key" "value" --metadata '{"source":"api"}'

# Get a value
wrangler kv key get --namespace-id abc123 "user:123"

# List keys (default: 1000)
wrangler kv key list --namespace-id abc123

# List with prefix filter
wrangler kv key list --namespace-id abc123 --prefix "user:"

# Delete a key
wrangler kv key delete --namespace-id abc123 "user:123"

# Use binding name instead of namespace-id (requires wrangler.toml)
wrangler kv key put --binding MY_KV "key" "value"

# Bulk put from JSON file (array of {key, value, expiration?, metadata?})
wrangler kv bulk put --namespace-id abc123 ./data.json

# data.json format:
# [
#   { "key": "k1", "value": "v1" },
#   { "key": "k2", "value": "v2", "expiration_ttl": 3600 }
# ]

# Bulk delete from JSON file (array of key strings)
wrangler kv bulk delete --namespace-id abc123 ./keys.json

[[kv_namespaces]]
binding = "CACHE"
id = "abc123..."          # Production namespace ID
preview_id = "xyz789..."  # Preview namespace (wrangler dev uses this)

// Worker usage
const value = await env.CACHE.get("key");
await env.CACHE.put("key", "value", { expirationTtl: 3600 });

# Create bucket
wrangler r2 bucket create my-bucket

# Create with location hint (for data residency)
wrangler r2 bucket create my-bucket --location eu

# List buckets
wrangler r2 bucket list

# Delete bucket (must be empty)
wrangler r2 bucket delete my-bucket

# Enable public access (serves objects at r2.dev subdomain)
wrangler r2 bucket catalog enable my-bucket

# CORS configuration
wrangler r2 bucket cors set my-bucket --rules '[{"allowedOrigins":["*"],"allowedMethods":["GET"]}]'

# Upload object
wrangler r2 object put my-bucket/path/to/file.jpg --file ./local-file.jpg

# Upload with content type
wrangler r2 object put my-bucket/image.jpg \
  --file ./image.jpg \
  --content-type "image/jpeg"

# Upload with custom metadata
wrangler r2 object put my-bucket/file.json \
  --file ./data.json \
  --content-type "application/json" \
  --metadata '{"source":"api","version":"2"}'

# Download object
wrangler r2 object get my-bucket/path/to/file.jpg --file ./output.jpg

# Delete object
wrangler r2 object delete my-bucket/path/to/file.jpg

[[r2_buckets]]
binding = "ASSETS"
bucket_name = "my-assets-bucket"
preview_bucket_name = "my-assets-preview"   # Local dev bucket

// Worker usage
const obj = await env.ASSETS.get("images/photo.jpg");
await env.ASSETS.put("uploads/file.pdf", body, {
  httpMetadata: { contentType: "application/pdf" },
  customMetadata: { userId: "123" }
});

// List objects
const list = await env.ASSETS.list({ prefix: "uploads/", limit: 100 });

// Delete
await env.ASSETS.delete("uploads/old-file.pdf");

# Create database
wrangler d1 create my-database

# List databases
wrangler d1 list

# Delete database
wrangler d1 delete my-database

# Get database info
wrangler d1 info my-database

# Run inline SQL command (production)
wrangler d1 execute my-database --command "SELECT * FROM users LIMIT 10"

# Run SQL file (production)
wrangler d1 execute my-database --file ./schema.sql

# Run locally (requires --local flag)
wrangler d1 execute my-database --local --command "SELECT COUNT(*) FROM users"

# Run SQL file locally
wrangler d1 execute my-database --local --file ./seed.sql

# Batch execute (multiple statements)
wrangler d1 execute my-database --file ./migration.sql --batch-size 100

# Create migration file (creates ./migrations/0001_init.sql)
wrangler d1 migrations create my-database "init"

# Apply all pending migrations (production)
wrangler d1 migrations apply my-database

# Apply locally
wrangler d1 migrations apply my-database --local

# List migration status
wrangler d1 migrations list my-database

# List local migration status
wrangler d1 migrations list my-database --local

-- migrations/0001_init.sql
CREATE TABLE users (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  email TEXT UNIQUE NOT NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_users_email ON users(email);

# Export database (backup)
wrangler d1 export my-database --output ./backup.sql

# Export specific table
wrangler d1 export my-database --table users --output ./users.sql

# Restore using time-travel (within retention window)
wrangler d1 time-travel restore my-database --bookmark <bookmark-id>

# List bookmarks for time-travel
wrangler d1 time-travel info my-database

[[d1_databases]]
binding = "DB"
database_name = "my-database"
database_id = "abc123-def456..."
migrations_dir = "./migrations"   # Optional, default: migrations/

// Worker usage
const result = await env.DB.prepare(
  "SELECT * FROM users WHERE email = ?"
).bind(email).first();

// Batch queries (atomic)
const [user, posts] = await env.DB.batch([
  env.DB.prepare("SELECT * FROM users WHERE id = ?").bind(userId),
  env.DB.prepare("SELECT * FROM posts WHERE user_id = ?").bind(userId),
]);

# Class definition (where the DO class lives)
[[durable_objects.bindings]]
name = "COUNTER"              # Binding name in Worker env
class_name = "Counter"        # Exported class name from Worker
# script_name = "other-worker"  # Optional: class from another Worker

# Migrations (required when adding/changing DO classes)
[[migrations]]
tag = "v1"
new_classes = ["Counter"]

# Renaming
[[migrations]]
tag = "v2"
renamed_classes = [{ from = "Counter", to = "CounterV2" }]

# Deleting
[[migrations]]
tag = "v3"
deleted_classes = ["OldCounter"]

export class Counter implements DurableObject {
  state: DurableObjectState;
  env: Env;

  constructor(state: DurableObjectState, env: Env) {
    this.state = state;
    this.env = env;
  }

  async fetch(request: Request): Promise<Response> {
    const count = (await this.state.storage.get<number>("count")) ?? 0;
    await this.state.storage.put("count", count + 1);
    return new Response(String(count + 1));
  }

  // Alarm pattern (scheduled task per DO instance)
  async alarm() {
    await doPeriodicWork(this.state, this.env);
    // Re-schedule
    await this.state.storage.setAlarm(Date.now() + 60_000);
  }
}

export default {
  async fetch(request: Request, env: Env) {
    const id = env.COUNTER.idFromName("global");  // Deterministic ID
    const stub = env.COUNTER.get(id);
    return stub.fetch(request);
  }
};

# Create Pages project
wrangler pages project create my-site

# List projects
wrangler pages project list

# Delete project
wrangler pages project delete my-site

# Deploy build output
wrangler pages deploy ./dist

# Deploy to specific project
wrangler pages deploy ./dist --project-name my-site

# Deploy to specific branch (creates preview deployment)
wrangler pages deploy ./dist --project-name my-site --branch feature/new-ui

# Deploy with commit message
wrangler pages deploy ./dist --project-name my-site --commit-message "feat: add new landing page"

# Set custom build config (usually done via dashboard or direct-upload)
wrangler pages deploy ./dist --project-name my-site --commit-dirty

# Functions live in /functions directory
# /functions/api/users.ts → handles /api/users
# /functions/api/[id].ts → handles /api/:id (dynamic route)

# Deploy with functions (automatic if /functions dir exists)
wrangler pages deploy ./dist --project-name my-site

# Local dev with functions
wrangler pages dev ./dist

# Local dev with specific port
wrangler pages dev ./dist --port 3000

// functions/api/users.ts
import type { EventContext } from "@cloudflare/workers-types";

export async function onRequestGet(ctx: EventContext<Env, any, any>) {
  const users = await ctx.env.DB.prepare("SELECT * FROM users").all();
  return Response.json(users.results);
}

# /dist/_redirects — static redirects/rewrites
/old-path  /new-path  301
/api/*     https://api.example.com/:splat  200   # Proxy (rewrite)

# /dist/_headers — custom response headers
/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff
  Content-Security-Policy: default-src 'self'

/assets/*
  Cache-Control: public, max-age=31536000, immutable

# Create queue
wrangler queues create my-queue

# List queues
wrangler queues list

# Delete queue
wrangler queues delete my-queue

# Add consumer (Worker that processes messages)
wrangler queues consumer add my-queue my-consumer-worker

# Remove consumer
wrangler queues consumer remove my-queue my-consumer-worker

# List consumers
wrangler queues consumer list my-queue

# Producer binding (push messages)
[[queues.producers]]
binding = "MY_QUEUE"
queue = "my-queue"

# Consumer binding (pull/process messages)
[[queues.consumers]]
queue = "my-queue"
max_batch_size = 10           # Messages per batch (default: 10, max: 100)
max_batch_timeout = 5         # Seconds to wait for full batch
max_retries = 3               # Retry failed messages
dead_letter_queue = "my-dlq"  # Route failed messages here
max_concurrency = 5           # Parallel consumer invocations

// Producer Worker
export default {
  async fetch(request: Request, env: Env) {
    await env.MY_QUEUE.send({ type: "email", userId: "123" });
    // Batch send
    await env.MY_QUEUE.sendBatch([
      { body: { type: "email", userId: "123" } },
      { body: { type: "sms", userId: "456" }, delaySeconds: 60 },
    ]);
    return new Response("Queued");
  }
};

// Consumer Worker
export default {
  async queue(batch: MessageBatch<QueueMessage>, env: Env) {
    for (const message of batch.messages) {
      try {
        await processMessage(message.body, env);
        message.ack();  // Explicit ack (or use batch.ackAll())
      } catch (e) {
        message.retry({ delaySeconds: 30 });  // Retry with backoff
      }
    }
  }
};

# Add secret (prompts for value interactively)
wrangler secret put MY_API_KEY

# List secrets (values are never shown)
wrangler secret list

# Delete secret
wrangler secret delete MY_API_KEY

# Bulk set secrets from JSON
echo '{"KEY1":"val1","KEY2":"val2"}' | wrangler secret bulk

# Set secret for specific environment
wrangler secret put MY_API_KEY --env staging

# .dev.vars (gitignored, equivalent of .env for Workers)
MY_API_KEY=local-dev-key-here
DATABASE_URL=postgres://localhost/mydb
JWT_SECRET=dev-secret-not-for-production

# Non-secret environment variables (committed to source control)
[vars]
ENVIRONMENT = "production"
API_VERSION = "v2"
LOG_LEVEL = "error"
MAX_RETRY = "3"

[env.staging.vars]
ENVIRONMENT = "staging"
LOG_LEVEL = "debug"

[triggers]
crons = [
  "0 * * * *",     # Every hour at :00
  "0 9 * * 1",     # Every Monday at 9:00 UTC
  "*/15 * * * *",  # Every 15 minutes
  "0 0 1 * *",     # First day of every month
]

export interface Env {
  DB: D1Database;
}

export default {
  // HTTP handler
  async fetch(request: Request, env: Env): Promise<Response> {
    return new Response("OK");
  },

  // Scheduled handler
  async scheduled(event: ScheduledEvent, env: Env, ctx: ExecutionContext) {
    // event.cron — the cron expression that triggered this
    // event.scheduledTime — Unix timestamp

    switch (event.cron) {
      case "0 * * * *":
        ctx.waitUntil(runHourlyCleanup(env));
        break;
      case "0 9 * * 1":
        ctx.waitUntil(sendWeeklyReport(env));
        break;
    }
  }
};

# Trigger scheduled event manually in local dev
curl "http://localhost:8787/__scheduled?cron=*+*+*+*+*"

# Stream errors only
wrangler tail --status 500 --format json | jq '{
  url: .event.request.url,
  error: .exceptions[0].message,
  timestamp: .eventTimestamp
}'

# Monitor POST requests
wrangler tail --method POST --method PUT

# Real-time log from specific IP
wrangler tail --ip 203.0.113.0

# All logs as pretty JSON
wrangler tail --format pretty

# Count error rate (last 100 events)
wrangler tail --status 500 --format json | head -100 | wc -l

# Enable verbose output
wrangler dev --log-level debug

# Inspector URL (Chrome DevTools)
wrangler dev   # Opens inspector at http://localhost:9229

# Use --inspect flag for explicit DevTools
wrangler dev --inspect

// vitest.config.ts
import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    environment: "miniflare",
    environmentOptions: {
      kvNamespaces: ["MY_KV"],
      d1Databases: ["MY_DB"],
    },
  },
});

// worker.test.ts
import { env } from "cloudflare:test";
import { describe, it, expect } from "vitest";
import worker from "./src/index";

describe("Worker", () => {
  it("returns 200", async () => {
    const response = await worker.fetch(
      new Request("http://localhost/"),
      env
    );
    expect(response.status).toBe(200);
  });
});

# api-worker/wrangler.toml
name = "api-worker"
main = "src/index.ts"
compatibility_date = "2024-11-01"

[[services]]
binding = "AUTH"
service = "auth-worker"    # Must be deployed first
environment = "production"

// api-worker: call auth-worker directly (no network hop)
const authResponse = await env.AUTH.fetch(
  new Request("https://auth/verify", {
    headers: { Authorization: request.headers.get("Authorization") ?? "" }
  })
);

# packages/
#   api-worker/wrangler.toml
#   auth-worker/wrangler.toml
#   shared/      ← shared utilities

# Deploy all workers from root
cd packages/api-worker && wrangler deploy
cd packages/auth-worker && wrangler deploy

# Or with turborepo/nx pipeline
turbo run deploy --filter=*-worker

# .github/workflows/deploy.yml
name: Deploy Workers

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Deploy Workers
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          command: deploy --env production

      # Apply D1 migrations before deploy
      - name: Apply D1 Migrations
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          command: d1 migrations apply my-database --env production

[build]
command = "npm run build"           # Build command
cwd = "."                           # Working directory

[build.upload]
format = "service-worker"           # "service-worker" or "modules"
main = "./dist/worker.js"

# Serve static assets from a directory alongside Worker code
assets = { directory = "./public", binding = "ASSETS" }

# Or with advanced config
[assets]
directory = "./dist"
binding = "ASSETS"
html_handling = "auto-trailing-slash"
not_found_handling = "single-page-application"   # SPA mode: all 404s → index.html

// Worker can serve assets + handle API routes
export default {
  async fetch(request: Request, env: Env) {
    const url = new URL(request.url);
    if (url.pathname.startsWith("/api/")) {
      return handleApi(request, env);
    }
    // Fall through to static asset serving
    return env.ASSETS.fetch(request);
  }
};

# 1. Upload new version without deploying
wrangler versions upload

# 2. Create split deployment (10% to new version)
wrangler deployments create \
  --version-id <new-version-id> \
  --version-percentage 10 \
  --version-id <old-version-id> \
  --version-percentage 90

# 3. Monitor with tail
wrangler tail --format json | jq '.scriptVersion'

# 4. Gradually shift traffic
# Repeat deployments create with 25%, 50%, 75%, 100%

# Full production worker example
name = "my-api"
main = "src/index.ts"
compatibility_date = "2024-11-01"
node_compat = true

[vars]
ENVIRONMENT = "production"

[[kv_namespaces]]
binding = "CACHE"
id = "prod-namespace-id"
preview_id = "dev-namespace-id"

[[d1_databases]]
binding = "DB"
database_name = "my-api-db"
database_id = "prod-db-id"

[[r2_buckets]]
binding = "UPLOADS"
bucket_name = "my-api-uploads"

[[queues.producers]]
binding = "JOBS"
queue = "background-jobs"

[[queues.consumers]]
queue = "background-jobs"
max_batch_size = 10
dead_letter_queue = "background-jobs-dlq"

[triggers]
crons = ["0 */4 * * *"]

[[migrations]]
tag = "v1"
new_classes = ["RateLimiter"]

[[durable_objects.bindings]]
name = "RATE_LIMITER"
class_name = "RateLimiter"

[env.staging]
name = "my-api-staging"
vars = { ENVIRONMENT = "staging" }

[env.staging.d1_databases]
[[env.staging.d1_databases]]
binding = "DB"
database_name = "my-api-db-staging"
database_id = "staging-db-id"