cloudflare-workers-dev-experience

Cloudflare Workers の開発者エクスペリエンス

Wrangler、Miniflare、最新のツールを使ったローカル開発環境のセットアップです。

クイックスタート

# 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

安全なインストール

bunx create-cloudflare のようなスキャフォールディングツールは、リモートコードをダウンロードして実行します。実行する前に、サプライチェーンセキュリティのベストプラクティスに従ってください。

• インストール後スクリプトをブロックする — npm config set ignore-scripts true（Bun ではデフォルトで無効です）
• クールダウン期間を設ける — 新しいパッケージバージョンがコミュニティによって審査されるまで、7 日間待ちます
• インストール前に監査する — socket package score npm <pkg> を実行するか、socket npm install <pkg> を使ってパッケージを確認します

Socket CLI の統合、クールダウンの設定、ロックファイルの検証、CI での適用など、セキュリティ設定の詳細については、dependency-upgrade スキルを読み込んでください。

必須の 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" }
  ]
}

重要なルール

1. ローカルテストには必ず wrangler dev を使う — Cloudflare ランタイムを正確にシミュレートします
2. compatibility_date を設定する — ランタイムの動作を制御します。四半期ごとに更新してください
3. ローカル開発にはプレビュー ID を使う — 本番環境のバインディングとは分けます
4. TypeScript を適切に設定する — @cloudflare/workers-types を使います
5. ソースマップを有効にする — 開発時に、より詳しいエラースタックを確認できます

防止できる主な 6 つのエラー

エラー	症状	防止策
モジュールが見つからない	デプロイ時のインポートエラー	tsconfig で "moduleResolution": "bundler" を設定する
バインディングが未定義	ローカルで env.KV is undefined	KV 名前空間の設定に preview_id を追加する
HMR が機能しない	変更が反映されない	ポートの競合を確認し、--local フラグを使う
D1 スキーマの不一致	ローカルでクエリが失敗する	ローカル DB でマイグレーションを実行する
型エラー	バインディングの型が見つからない	wrangler types で型を生成する
CORS の問題	ブラウザーがリクエストをブロックする	開発用ハンドラーに CORS ヘッダーを追加する

ローカル開発ワークフロー

# 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 の設定

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": {
    "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'"
  }
}

デバッグ

コンソールログ

// 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...
  }
};

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 でのデバッグ

.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
    }
  ]
}

リファレンスを読み込むタイミング

タスクに応じて、該当するリファレンスを読み込んでください。

• プロジェクトをセットアップする場合 → セットアップの全手順については references/local-development.md を読み込みます
• wrangler を設定する場合 → すべての設定オプションについては references/wrangler-config.md を読み込みます
• 問題をデバッグする場合 → デバッグ手法については references/debugging-tools.md を読み込みます

テンプレート

テンプレート	目的	使用する場面
templates/wrangler-config.jsonc	wrangler の完全な設定	新しいプロジェクトを始めるとき
templates/dev-script.ts	開発用ユーティリティ	開発用ヘルパーを追加するとき

スクリプト

スクリプト	目的	コマンド
scripts/dev-setup.sh	開発環境を初期化する	./dev-setup.sh

リソース

• Wrangler CLI：https://developers.cloudflare.com/workers/wrangler/
• 設定：https://developers.cloudflare.com/workers/wrangler/configuration/
• ローカル開発：https://developers.cloudflare.com/workers/testing/local-development/