wrangler-coder

Wrangler Coder

Wrangler は、Workers、Pages、D1、R2、KV、Queues、AI 用の Cloudflare 公式 CLI です。

インストール

# npm
npm install -g wrangler

# pnpm
pnpm add -g wrangler

# Verify installation
wrangler --version

認証

# Interactive login (opens browser)
wrangler login

# Check authentication status
wrangler whoami

# Logout
wrangler logout

環境変数：

# API Token (preferred for CI/CD)
export CLOUDFLARE_API_TOKEN="your-api-token"

# Or with 1Password
CLOUDFLARE_API_TOKEN=op://Infrastructure/Cloudflare/wrangler_token

# Account ID (optional, can be in wrangler.toml)
export CLOUDFLARE_ACCOUNT_ID="your-account-id"

プロジェクトの初期化

# Create new Worker project
wrangler init my-worker

# Create from template
wrangler init my-worker --template cloudflare/worker-template

# Initialize in existing directory
wrangler init

wrangler.toml の設定

基本的な Worker

name = "my-worker"
main = "src/index.ts"
compatibility_date = "2024-12-01"

# Account ID (can also use CLOUDFLARE_ACCOUNT_ID env var)
account_id = "your-account-id"

# Worker settings
workers_dev = true  # Enable *.workers.dev subdomain

ルートを設定した Worker

name = "api-worker"
main = "src/index.ts"
compatibility_date = "2024-12-01"
account_id = "your-account-id"

# Custom domain routes
routes = [
  { pattern = "api.example.com/*", zone_name = "example.com" },
  { pattern = "example.com/api/*", zone_name = "example.com" }
]

マルチ環境の設定

name = "my-worker"
main = "src/index.ts"
compatibility_date = "2024-12-01"
account_id = "your-account-id"

# Development (default)
workers_dev = true

# Staging environment
[env.staging]
name = "my-worker-staging"
routes = [
  { pattern = "staging-api.example.com/*", zone_name = "example.com" }
]
vars = { ENVIRONMENT = "staging" }

# Production environment
[env.production]
name = "my-worker-production"
routes = [
  { pattern = "api.example.com/*", zone_name = "example.com" }
]
vars = { ENVIRONMENT = "production" }

Cloudflare の製品

製品	リソース
KV Namespaces	references/kv-namespaces.md
D1 Database & R2 Storage	references/d1-r2.md
Queues & Durable Objects	references/queues-durable-objects.md
Workers AI	references/workers-ai.md
Cloudflare Pages	references/pages.md

シークレット管理

# Add secret
wrangler secret put API_KEY
# (prompts for value)

# Add secret for specific environment
wrangler secret put API_KEY --env production

# List secrets
wrangler secret list

# Delete secret
wrangler secret delete API_KEY

# Bulk secrets from .dev.vars file (local dev only)
# Create .dev.vars file:
# API_KEY=xxx
# DB_PASSWORD=yyy

export interface Env {
  API_KEY: string;
  DB_PASSWORD: string;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    // Access secrets from env
    const apiKey = env.API_KEY;
    return new Response(`Key length: ${apiKey.length}`);
  }
};

開発ワークフロー

ローカル開発

# Start local dev server
wrangler dev

# With specific environment
wrangler dev --env staging

# Custom port
wrangler dev --port 8787

# Remote mode (uses Cloudflare's network)
wrangler dev --remote

# Local mode with persistent storage
wrangler dev --persist-to ./data

テスト

# Run tests with vitest (recommended)
npm install -D vitest @cloudflare/vitest-pool-workers

# vitest.config.ts
# import { defineWorkersConfig } from '@cloudflare/vitest-pool-workers/config';
# export default defineWorkersConfig({
#   test: { poolOptions: { workers: { wrangler: { configPath: './wrangler.toml' } } } }
# });

デプロイ

# Deploy to workers.dev
wrangler deploy

# Deploy to specific environment
wrangler deploy --env production

# Dry run (show what would be deployed)
wrangler deploy --dry-run

# Deploy with custom name
wrangler deploy --name my-custom-worker

ログとデバッグ

# Tail logs (real-time)
wrangler tail

# Tail specific environment
wrangler tail --env production

# Filter logs
wrangler tail --status error
wrangler tail --search "user-id-123"
wrangler tail --ip 1.2.3.4

# View deployment versions
wrangler versions list

# Rollback to previous version
wrangler rollback

Worker の完全な例

本番環境ですぐに使える、D1、KV、R2 のバインディング、マルチ環境設定、CORS 処理を備えた Worker については、references/worker-example.md を参照してください。

ベストプラクティス

• compatibility_date を固定する - デプロイ間で動作を再現可能にします
• 環境を使う - 同じファイル内でステージング環境と本番環境の設定を分けます
• CLI でシークレットを扱う - シークレットをコミットせず、wrangler secret put を使用します
• ローカルでの永続化 - 一貫したローカル開発状態を保つには --persist-to を使用します
• 本番環境でログを監視する - wrangler tail --status error で問題をデバッグします
• wrangler.toml をバージョン管理する - 設定の変更を追跡します
• ローカルシークレットには .dev.vars を使う - .gitignore に追加します
• D1 の操作をバッチ処理する - env.DB.batch() でレイテンシを減らします
• 戦略的にキャッシュする - 頻繁にアクセスされるデータには KV を使用します
• エラーを適切に処理する - 適切な HTTP ステータスコードを返します