【Cloudflare】Wrangler設定ファイルの備忘録

Cloudflare Workers を使って開発を進めていると、設定ファイルである wrangler.toml の項目が多岐にわたるため、どの設定が何を意味するのか、どう書けば良いのかを忘れがちです。特に、環境ごとの設定や各種バインディングが増えてくると、その都度ドキュメントを確認するのが少し手間に感じていました。

基本的な違い

Wranglerの設定ファイルは、wrangler.toml (TOML形式) と wrangler.json (JSON形式) の両方をサポートしています。

TOML形式: 人間にとって読みやすく、コメント（#）が使えるのが特徴です。手動で編集することが多い場合はこちらが便利だと感じます。

JSON形式: プログラムでの処理や、他のツールとの連携がしやすい形式です。wrangler.jsonc であればコメントも使えます。

1.基本設定

まずはWorkerを動作させるための最小限の設定です。

最小構成の例

wrangler.toml

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

wrangler.json

{
  "name": "my-worker",
  "main": "src/index.js",
  "compatibility_date": "2024-01-01"
}

詳細な基本設定

もう少し詳細な設定項目を含めると以下のようになります。

wrangler.toml

# Worker名（必須）
name = "production-api"

# エントリーポイントのファイルパス（必須）
main = "src/index.ts"

# 互換性日付（必須）
compatibility_date = "2024-01-01"

# アカウントID（オプション）
account_id = "abc123def456"

# 特定の互換性フラグを有効にする
compatibility_flags = ["nodejs_compat", "experimental_streaming"]

# workers.dev サブドメインを有効にするか
workers_dev = true

wrangler.json

{
  "name": "production-api",
  "main": "src/index.ts",
  "compatibility_date": "2024-01-01",
  "account_id": "abc123def456",
  "compatibility_flags": ["nodejs_compat", "experimental_streaming"],
  "workers_dev": true
}

2. 環境設定 (env)

本番（production）、ステージング（staging）、開発（development）など、環境ごとに設定を切り替えたい場合に重宝します。

wrangler.toml

# デフォルト（本番）環境
name = "my-worker"
main = "src/index.js"
compatibility_date = "2024-01-01"

[vars]
API_ENDPOINT = "https://api.production.com"

[[kv_namespaces]]
binding = "MY_KV"
id = "production_kv_id"

# ステージング環境
[env.staging]
name = "my-worker-staging"
vars = { API_ENDPOINT = "https://api.staging.com" }

[[env.staging.kv_namespaces]]
binding = "MY_KV"
id = "staging_kv_id"

wrangler.json

{
  "name": "my-worker",
  "main": "src/index.js",
  "compatibility_date": "2024-01-01",
  "vars": {
    "API_ENDPOINT": "https://api.production.com"
  },
  "kv_namespaces": [
    {
      "binding": "MY_KV",
      "id": "production_kv_id"
    }
  ],
  "env": {
    "staging": {
      "name": "my-worker-staging",
      "vars": {
        "API_ENDPOINT": "https://api.staging.com"
      },
      "kv_namespaces": [
        {
          "binding": "MY_KV",
          "id": "staging_kv_id"
        }
      ]
    }
  }
}

3. ルーティング設定 (routes)

Workerを特定のドメインやパスに紐付けます。

wrangler.toml

# 複数のルートを設定
[[routes]]
pattern = "shop.example.com"
custom_domain = true

[[routes]]
pattern = "api.example.com/v1/*"
zone_name = "example.com"

# または、シンプルなルート指定
# route = "example.com/*"

wrangler.json

{
  "routes": [
    {
      "pattern": "shop.example.com",
      "custom_domain": true
    },
    {
      "pattern": "api.example.com/v1/*",
      "zone_name": "example.com"
    }
  ]
  // または
  // "route": "example.com/*"
}

4. バインディング設定

KV、R2、D1などのCloudflareサービスをWorkerコード内から利用するための設定です。これが一番種類が多くて覚えにくい部分でした。

KV Namespace

[[kv_namespaces]]
binding = "USER_DATA" # コード内でアクセスする際の変数名
id = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" # 本番環境のID
preview_id = "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy" # プレビュー環境のID

R2 Buckets

[[r2_buckets]]
binding = "MY_BUCKET"
bucket_name = "production-files"
preview_bucket_name = "preview-files"

D1 Database

[[d1_databases]]
binding = "DB"
database_name = "production-db"
database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
migrations_dir = "d1/migrations" # マイグレーションファイルのディレクトリ

Durable Objects

# バインディング設定
[[durable_objects.bindings]]
name = "COUNTER"
class_name = "CounterDurableObject"

# マイグレーション設定
[[migrations]]
tag = "v1"
new_classes = ["CounterDurableObject"]

Queues

# プロデューサー（キューにメッセージを送る側）
[[queues.producers]]
queue = "task-queue"
binding = "MY_QUEUE"

# コンシューマー（キューからメッセージを受け取る側）
[[queues.consumers]]
queue = "task-queue"
max_batch_size = 10
max_retries = 5

Workers AI

[ai]
binding = "AI"

Service Bindings

他のWorkerをサービスとして呼び出すための設定です。

[[services]]
binding = "AUTH_SERVICE"
service = "auth-worker" # 呼び出すWorkerの名前

5. ビルド・バンドル設定 (build, rules)

TypeScriptのコンパイルや、テキスト・バイナリファイルなどをWorkerに含めるための設定です。

wrangler.toml

# カスタムビルドコマンド
[build]
command = "npm run build"
watch_dir = "src"

# モジュールルール
[[rules]]
type = "Text"
globs = ["**/*.md", "**/*.txt"]

[[rules]]
type = "Data"
globs = ["**/*.bin"]

# 最適化
minify = true

wrangler.json

{
  "build": {
    "command": "npm run build",
    "watch_dir": "src"
  },
  "rules": [
    {
      "type": "Text",
      "globs": ["**/*.md", "**/*.txt"]
    },
    {
      "type": "Data",
      "globs": ["**/*.bin"]
    }
  ],
  "minify": true
}

6. 開発サーバー設定 (dev)

wrangler dev を実行する際のローカルサーバーの設定です。

wrangler.toml

[dev]
ip = "0.0.0.0"
port = 8787
local_protocol = "http"

wrangler.json

{
  "dev": {
    "ip": "0.0.0.0",
    "port": 8787,
    "local_protocol": "http"
  }
}

7. その他の設定

Cron Triggers

スケジュール実行のための設定です。

[triggers]
crons = ["*/5 * * * *", "0 0 * * *"]

静的アセット (Pages Functions)

functions ディレクトリと連携して静的サイトを配信する場合の設定です。

[assets]
directory = "./public"