Wrangler

Wrangler CLI

Deploy, develop, and manage Cloudflare Workers and associated resources.

FIRST: Verify Wrangler Installation

wrangler --version  # Requires v4.x+

If not installed:

npm install -D wrangler@latest

Key Guidelines

• Use wrangler.jsonc: Prefer JSON config over TOML. Newer features are JSON-only.
• Set compatibility_date: Use a recent date (within 30 days).
• Generate types after config changes: Run wrangler types to update TypeScript bindings.
• Local dev defaults to local storage: Bindings use local simulation unless remote: true.
• Validate config before deploy: Run wrangler deploy --dry-run to catch errors early.
• Use environments for staging/prod: Define env.staging and env.production in config.

Quick Start: New Worker

npx wrangler init my-worker
npx create-cloudflare@latest my-app  # With a framework

Quick Reference: Core Commands

Configuration (wrangler.jsonc)

Minimal Config

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

Full Config with Bindings

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-01-01",
  "compatibility_flags": ["nodejs_compat_v2"],
  "vars": { "ENVIRONMENT": "production" },
  "kv_namespaces": [{ "binding": "KV", "id": "<KV_NAMESPACE_ID>" }],
  "r2_buckets": [{ "binding": "BUCKET", "bucket_name": "my-bucket" }],
  "d1_databases": [{ "binding": "DB", "database_name": "my-db", "database_id": "<DB_ID>" }],
  "ai": { "binding": "AI" },
  "vectorize": [{ "binding": "VECTOR_INDEX", "index_name": "my-index" }],
  "hyperdrive": [{ "binding": "HYPERDRIVE", "id": "<HYPERDRIVE_ID>" }],
  "durable_objects": { "bindings": [{ "name": "COUNTER", "class_name": "Counter" }] },
  "triggers": { "crons": ["0 * * * *"] },
  "env": {
    "staging": { "name": "my-worker-staging", "vars": { "ENVIRONMENT": "staging" } }
  }
}

Generate Types from Config

wrangler types                      # Generate worker-configuration.d.ts
wrangler types ./src/env.d.ts       # Custom output path
wrangler types --check              # Check types are up to date (CI)

Local Development

wrangler dev                        # Local mode (default)
wrangler dev --env staging          # With specific environment
wrangler dev --local                # Force local-only
wrangler dev --remote               # Remote mode (legacy)
wrangler dev --port 8787            # Custom port
wrangler dev --live-reload          # Live reload for HTML changes
wrangler dev --test-scheduled       # Test scheduled/cron handlers
# Then visit: http://localhost:8787/__scheduled

Remote Bindings for Local Dev

Use remote: true in binding config for real resources while running locally:

{
  "r2_buckets": [{ "binding": "BUCKET", "bucket_name": "my-bucket", "remote": true }],
  "ai": { "binding": "AI", "remote": true },
  "vectorize": [{ "binding": "INDEX", "index_name": "my-index", "remote": true }]
}

Recommended remote: AI (required), Vectorize, Browser Rendering, mTLS, Images.

Local Secrets

Create .dev.vars:

API_KEY=local-dev-key
DATABASE_URL=postgres://localhost:5432/dev

Deployment

wrangler deploy                     # Deploy to production
wrangler deploy --env staging       # Deploy specific environment
wrangler deploy --dry-run           # Validate without deploying
wrangler deploy --keep-vars         # Keep dashboard-set variables
wrangler deploy --minify            # Minify code

Manage Secrets

wrangler secret put API_KEY                  # Set interactively
echo "value" | wrangler secret put API_KEY   # Set from stdin
wrangler secret list                         # List secrets
wrangler secret delete API_KEY               # Delete
wrangler secret bulk secrets.json            # Bulk from JSON

Versions and Rollback

wrangler versions list
wrangler versions view <VERSION_ID>
wrangler rollback
wrangler rollback <VERSION_ID>

Storage & Compute Services

상세 CLI 레퍼런스: references/storage-services.md (KV, R2, D1, Vectorize, Hyperdrive)

상세 CLI 레퍼런스: references/compute-services.md (AI, Queues, Containers, Workflows, Pipelines, Secrets Store, Pages)

Observability

wrangler tail                       # Stream live logs
wrangler tail my-worker             # Tail specific Worker
wrangler tail --status error        # Filter by status
wrangler tail --format json         # JSON output

Config: "observability": { "enabled": true, "head_sampling_rate": 1 }

Performance

wrangler check startup                       # Worker 시작(startup) 단계 CPU 프로파일 생성
wrangler check startup --args="--no-bundle"  # deploy를 --no-bundle로 할 때

wrangler check startup은 Worker의 시작 단계 CPU 프로파일을 만들어, 시작 시간 한도를 초과하는 스크립트를 찾게 해줍니다. 생성된 프로파일을 Chrome DevTools로 import하거나 VSCode에서 열어 flamegraph로 분석합니다.

• 측정은 로컬 머신 CPU 기준이라 Cloudflare 실제 시작 시간과 절대값이 다릅니다 — "전체 시간"이 아니라 "어디에 시간이 쓰이는지"를 보는 용도.
• 시작 시간 한도 초과로 배포가 실패하면 Wrangler가 자동으로 CPU 프로파일을 생성합니다.
• 주의: wrangler check는 이 startup 서브커맨드뿐 — 설정 검증 명령이 아닙니다(설정/빌드 검증은 wrangler deploy --dry-run).

Testing with Vitest

npm install -D @cloudflare/vitest-pool-workers vitest

// vitest.config.ts
import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";

export default defineWorkersConfig({
  test: {
    poolOptions: {
      workers: { wrangler: { configPath: "./wrangler.jsonc" } },
    },
  },
});

Troubleshooting

Best Practices

1. Version control wrangler.jsonc: Source of truth for Worker config.
2. Use automatic provisioning: Omit resource IDs for auto-creation.
3. Run wrangler types in CI: Catch binding mismatches.
4. Use environments: Separate staging/production.
5. Set compatibility_date: Update quarterly.
6. Use .dev.vars for local secrets: Never commit secrets.
7. Test locally first: wrangler dev before deploying.
8. Use --dry-run before major deploys.