Wranglerとは？ Cloudflare Workers開発ツール徹底解説

はじめに：エッジコンピューティングとCloudflare Workersの台頭

インターネットの進化に伴い、ユーザーはWebアプリケーションに対してますます高速で応答性の高い体験を求めるようになりました。これまでの多くのアプリケーションは、特定のリージョンにあるデータセンターのサーバーで動作していましたが、ユーザーから地理的に離れている場合、ネットワーク遅延（レイテンシ）が発生し、パフォーマンスの低下を招くことが避けられませんでした。

このような課題を解決するために注目されているのが、「エッジコンピューティング」です。エッジコンピューティングでは、アプリケーションの処理をユーザーに地理的に近いネットワークのエッジ（末端）で実行します。これにより、データ転送距離が短縮され、レイテンシが大幅に削減されます。

Cloudflare Workersは、このエッジコンピューティングの概念を具現化した代表的なサービスの一つです。Cloudflareが世界中に展開する広大なエッジネットワーク上で、JavaScript、WebAssembly、あるいはその他の互換性のある言語で記述されたコードを実行できます。これは、従来のサーバーレス関数（AWS Lambdaなど）が特定のリージョン内で動作するのに対し、Cloudflare Workersはユーザーのリクエストが発生した最も近いエッジロケーションで実行されるという点で画期的です。

Workersを利用することで、APIエンドポイントの作成、既存サービスの認証・リクエスト処理の強化、静的サイトの高速配信、A/Bテスト、マイクロサービスの構築など、様々なユースケースを低レイテンシかつスケーラブルに実現できます。サーバー管理は不要で、従量課金モデルのためコスト効率も優れています。

しかし、このような分散環境で動作するアプリケーションの開発、テスト、デプロイは、従来の開発手法とは異なる複雑さ伴います。コードの記述だけでなく、エッジ環境特有のバインディング（永続ストレージや他のWorkersとの連携）、環境設定、デプロイメントパイプラインの構築など、考慮すべき点が多岐にわたります。

ここで登場するのが、Cloudflare Workersのための公式開発ツール「Wrangler」です。Wranglerは、Workersプロジェクトのライフサイクル全体（作成、開発、テスト、デプロイ、管理）を効率化するために設計された強力なコマンドラインインターフェース（CLI）ツールです。Wranglerなくして、Workers開発を本格的に行うことは困難と言えるでしょう。

この記事では、Wranglerとは何か、その主要な機能、そしてCloudflare Workers開発においてWranglerをどのように活用するのかを、初心者から上級者まで理解できるよう、詳細かつ体系的に解説します。Wranglerの基本的な使い方から、設定ファイルの詳細、ローカル開発環境の構築、各種リソース（KV、Durable Objects、R2など）との連携、デプロイ戦略、テスト・CI/CD、さらには最新の機能や実践的なヒントまで、幅広く網羅します。

Workers開発を始めようとしている方、Wranglerの機能を最大限に活用したいと考えている方にとって、この記事が確固たるガイドとなることを願っています。

Cloudflare Workersとは？その仕組みと特徴

Wranglerの詳細に入る前に、開発対象であるCloudflare Workersについてもう少し詳しく理解しておきましょう。WranglerはWorkersの機能を最大限に引き出すためのツールであり、Workersの特性を理解することがWranglerの活用においても不可欠です。

Workersの仕組み：V8 Isolates

Cloudflare Workersの最も特徴的な仕組みの一つは、Google ChromeのV8 JavaScriptエンジンが採用している「Isolates」に基づいていることです。Isolatesは、非常に軽量でセキュアなサンドボックス環境を提供します。従来のサーバーレス関数がコンテナや仮想マシン上で動作するのに対し、Workersは単一のプロセス内で多数のIsolatesを同時に実行できます。

このIsolatesベースのアーキテクチャは、以下の利点をもたらします。

超高速なCold Start: 新しいリクエストが来た際に新しいインスタンスを立ち上げるオーバーヘッドが極めて小さいため、Cold Start（アイドル状態からの初回リクエスト処理開始までの遅延）がほとんどありません。
高いセキュリティ: 各Isolateは厳密に分離されており、互いのメモリや状態にアクセスできません。悪意のあるコードが他のIsolateやホストシステムに影響を与えるリスクを軽減します。
高い密度とスケーラビリティ: 単一のサーバープロセス上で多数のIsolatesを効率的に実行できるため、リソース利用効率が高く、大量のリクエストに対しても迅速にスケールアウトできます。
低コスト: リソース利用効率が高いため、従量課金モデルにおいてコストを低く抑えることが可能です。

Workersの主な特徴

エッジ実行: 世界中のCloudflareエッジロケーションで実行されるため、ユーザーに近い場所でコードが実行され、レイテンシが最小限に抑えられます。
サーバーレス: インフラのプロビジョニング、管理、スケーリングはすべてCloudflareが行います。開発者はコードの記述に集中できます。
多様な言語サポート: JavaScript/TypeScriptが主要ですが、WebAssembly（Rust, C++, Goなどからコンパイル）も強力にサポートしており、パフォーマンスが重要な処理にも対応できます。
強力なエコシステム: キーバリューストア（KV）、ステートフルなオブジェクト（Durable Objects）、オブジェクトストレージ（R2）、リレーショナルデータベース（D1）など、エッジで利用可能な多様な永続ストレージやサービスと容易に連携できます。
柔軟なデプロイメント:特定のルートパターンやゾーン全体にスクリプトを関連付けることができます。
Workers AI: エッジでのAI推論実行環境も統合されています。

従来のサーバーレス（例: AWS Lambda）との比較

特徴	Cloudflare Workers	従来のサーバーレス (例: AWS Lambda)
実行場所	Cloudflareエッジネットワーク (全世界)	特定のリージョン内のデータセンター
実行環境	V8 Isolates	コンテナ/VM
Cold Start	ほぼゼロ	数十ms〜数秒
レイテンシ	ユーザーに近く低レイテンシ	リージョンに依存し、レイテンシが発生しうる
実行時間制限	デフォルト 50ms (延長可能)	最大15分など（サービスによる）
課金モデル	リクエスト数 + 実行時間（非常に短い）	リクエスト数 + 実行時間
永続ストレージ	KV, DO, R2, D1 (エッジ向け)	S3, DynamoDB, RDS (リージョン内)
開発体験	Wrangler CLIによる効率化	各クラウドプロバイダのツール/CLI

Workersは、主にI/Oバウンドな処理や、ユーザーリクエストをエッジで処理し、バックエンドサービスへの負荷を軽減したり、ユーザー体験を向上させたりするユースケースに非常に適しています。従来のサーバーレスは、より長時間実行される処理や、特定のリージョン内のプライベートネットワークリソースへのアクセスが必要な場合に適していることがあります。Workersと従来のサーバーレスは排他的なものではなく、組み合わせて利用することも一般的です。

Wranglerとは？その役割と重要性

Cloudflare Workersの強力な機能とエッジコンピューティングのメリットを享受するために、開発者はWranglerを主要なツールとして利用します。Wranglerは、Cloudflareが公式に提供するオープンソースのCLIツールであり、Workersの開発体験を劇的に向上させます。

なぜWranglerが必要なのか？

WorkersコードはJavaScriptやWebAssemblyなどの形式で記述されますが、単にコードを書くだけではエッジネットワーク上で実行できません。Workersをデプロイし、特定のURLパターンに関連付け、永続ストレージなどのリソースと連携させるためには、CloudflareのAPIを通じて様々な設定を行う必要があります。

Wranglerが登場する前は、これらの操作を手動で行うか、自作のスクリプトを使用する必要がありました。これは非常に手間がかかり、エラーが発生しやすく、開発プロセスを遅延させる要因となっていました。

Wranglerは、これらの複雑なタスクを抽象化し、コマンド一つで実行できるようにすることで、Workers開発者がコードの記述そのものに集中できるようにします。

Wranglerの主な役割

Wranglerは、Workersプロジェクトのライフサイクル全体にわたる以下のような主要なタスクをサポートします。

プロジェクトの初期化: 新しいWorkersプロジェクトをテンプレートから素早く作成します。
依存関係の管理とビルド: JavaScript/TypeScriptのトランスパイル、バンドル、WebAssemblyモジュールのビルドなど、デプロイ可能なWorkersスクリプトを生成します。
ローカル開発環境: Cloudflare Workersのエッジ環境をローカルでエミュレートし、高速なイテレーション開発とテストを可能にします。（Miniflareから進化したworkerdを利用）
設定管理: Workersの名前、ルート、バインディング（KV, DO, R2など）、環境変数、シークレットなどの設定を、構成ファイル（wrangler.toml）を通じて管理します。
デプロイ: 開発中のWorkersスクリプトをCloudflareのエッジネットワークにデプロイします。バージョン管理や環境ごとのデプロイもサポートします。
リソース管理: KV名前空間、Durable Objectsクラス、R2バケットなど、Workersが連携するリソースの作成や管理をコマンドラインから行えます。
ログと監視: デプロイされたWorkersの実行ログをリアルタイムで確認できます。
Secrets管理: APIキーやパスワードなどの機密情報を安全に管理・バインディングします。

Wranglerは、これらの機能を一元的に提供することで、Workers開発の生産性、信頼性、効率性を飛躍的に向上させます。Workers開発を始める上で、Wranglerの習得は必須と言えるでしょう。

Wranglerのインストールと認証

Wranglerを使用するための最初のステップは、ツールのインストールとCloudflareアカウントとの認証です。

Node.jsのインストール

WranglerはNode.js環境で動作するnpmパッケージとして提供されています。まだNode.jsがインストールされていない場合は、公式ウェブサイト（https://nodejs.org/）からダウンロードしてインストールしてください。バージョン16.0.0以上が推奨されています。

Node.jsのインストールが完了したら、ターミナル（コマンドプロンプト）を開き、以下のコマンドでバージョンを確認できます。

bash node -v npm -v

Wranglerのインストール

Wranglerはnpmパッケージとしてグローバルにインストールすることを推奨します。これにより、どのディレクトリからでもwranglerコマンドを実行できるようになります。

bash npm install -g wrangler

npmの代わりにYarnやpnpmを使用している場合は、それぞれのパッケージマネージャーのコマンドを使用してください。

“`bash

Yarnの場合

yarn global add wrangler

pnpmの場合

pnpm add -g wrangler
“`

インストールが完了したら、以下のコマンドでWranglerのバージョンを確認し、正しくインストールされたか確認します。

“`bash
wrangler –version

または

wrangler version
“`

Cloudflareアカウントとの認証 (`wrangler login`)

Wranglerを使ってWorkersをデプロイしたり、リソースを管理したりするには、Cloudflareアカウントへの認証が必要です。wrangler loginコマンドを使用します。

bash wrangler login

このコマンドを実行すると、ブラウザが開き、Cloudflareのログイン画面が表示されます。Cloudflareアカウントの認証情報を入力してログインしてください。ログインに成功すると、Wranglerに権限を付与するかどうか尋ねられます。許可することで、WranglerがCloudflareアカウントのリソースにアクセスできるようになります。

ターミナルに戻ると、認証が成功した旨のメッセージが表示されます。認証情報はローカルのユーザーディレクトリに安全に保存されます。

補足: CI/CD環境などでブラウザを開けない場合は、Cloudflare APIトークンを使用して認証することも可能です。CloudflareダッシュボードでAPIトークンを作成し、環境変数（CF_API_TOKEN）として設定するか、wrangler config tokenコマンドを使用します。ただし、通常の手動開発ではwrangler loginが最も簡単で推奨される方法です。

これで、Wranglerを使用する準備が整いました。次のセクションでは、新しいWorkersプロジェクトの作成方法を学びます。

Workersプロジェクトの作成 (`wrangler init`)

Wranglerをインストールし、Cloudflareアカウントとの認証が完了したら、いよいよWorkersプロジェクトを作成します。wrangler initコマンドは、新しいプロジェクト構造を自動的に生成し、開発を開始するための boilerplate コードを提供します。

`wrangler init` コマンドの使い方

新しいプロジェクトを作成したいディレクトリに移動し、以下のコマンドを実行します。

bash wrangler init my-workers-app

ここで、my-workers-appは作成するプロジェクトのディレクトリ名です。このコマンドを実行すると、Wranglerはいくつかの質問を対話形式で尋ねます。

使用するフレームワークは？
- "None": フレームワークを使用せず、基本的なWorkersコードで開始します。
- "Fetch handler (default)": 標準的なFetchイベントハンドラーを持つWorkersプロジェクトを作成します。（最も一般的）
- "Scheduled handler": Cronトリガーで定期的に実行されるWorkersプロジェクトを作成します。
- "Queue consumer": Cloudflare Queuesからのメッセージを処理するWorkersプロジェクトを作成します。
- "Durable Object": Durable Objectsのクラスを作成します。
- "Smart Container": 複数のWorkersを単一のIsolateで実行するプロジェクトを作成します。（高度）
- "Trace Worker": Trace APIを使用してWorkersの実行トレースを記録するプロジェクトを作成します。（診断用）
- "AI Worker": Workers AIを利用するプロジェクトを作成します。
- "D1 Worker": Cloudflare D1データベースを利用するプロジェクトを作成します。
- "R2 Worker": Cloudflare R2オブジェクトストレージを利用するプロジェクトを作成します。
多くの場合は、"Fetch handler (default)"を選択します。
TypeScriptを使用しますか？ (はい/いいえ)
- TypeScriptを使用する場合はYesを選択します。TypeScriptプロジェクトに必要な設定ファイル（tsconfig.json）や依存関係が自動的に追加されます。
Gitリポジトリとして初期化しますか？ (はい/いいえ)
- Yesを選択すると、.gitignoreファイルが作成され、Gitリポジトリとして初期化されます。

これらの質問に答えると、Wranglerは指定したディレクトリ名で新しいディレクトリを作成し、必要なファイルとディレクトリ構造を生成します。

例：Fetch handlerでTypeScriptを使用する場合

“`bash
$ wrangler init my-workers-app

✔ Where do you want to create your application? … my-workers-app
✔ What type of worker do you want to create? › Fetch handler (default)
✔ Would you like to use TypeScript? … Yes
✔ Would you like to use Git to manage this Worker? … Yes
✔ Would you like to generate a package.json file? … Yes
✔ Would you like to install dependencies? … Yes

プロジェクト作成と依存関係のインストールが実行される

🚀 Created /Users/your_username/my-workers-app/.gitignore
🚀 Created /Users/your_username/my-workers-app/tsconfig.json
🚀 Created /Users/your_username/my-workers-app/src/index.ts
🚀 Created /Users/your_username/my-workers-app/package.json
🚀 Created /Users/your_username/my-workers-app/wrangler.toml
🎉 Your worker was created at my-workers-app
“`

プロジェクト構造

wrangler initによって生成されたプロジェクトの基本的な構造は以下のようになります。（TypeScriptを使用した場合）

my-workers-app/ ├── .gitignore # Git用の無視ファイル ├── package.json # npm/yarnの依存関係やスクリプトを定義 ├── tsconfig.json # TypeScriptの設定ファイル ├── wrangler.toml # Wranglerの設定ファイル（非常に重要！） └── src/ └── index.ts # Workersのメインコード

src/index.ts (または src/index.js): Workersのロジックを記述するメインファイルです。Fetchイベントをリッスンし、リクエストに対するレスポンスを生成するのが一般的です。
- デフォルトで生成されるコードは以下のようになります。
“`typescript
export interface Env {
// Example binding to KV. Learn more at https://developers.cloudflare.com/workers/runtime-apis/kv/
// MY_KV_NAMESPACE: KVNamespace;
//
// Example binding to Durable Object. Learn more at https://developers.cloudflare.com/workers/runtime-apis/durable-objects/
// MY_DURABLE_OBJECT: DurableObjectNamespace;
//
// Example binding to R2. Learn more at https://developers.cloudflare.com/workers/runtime-apis/r2/
// MY_BUCKET: R2Bucket;
//
// Example binding to a Service. Learn more at https://developers.cloudflare.com/workers/runtime-apis/workers#service-bindings
// MY_SERVICE: Fetcher;
//
// Example binding to a Queue. Learn more at https://developers.cloudflare.com/queues/javascript-apis/
// MY_QUEUE: Queue;
//
// Example binding to a D1 Database. Learn more at https://developers.cloudflare.com/d1/
// DB: D1Database;
}

export default {
async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise {
return Response.json({
message: ‘Hello World!’,
requestUrl: request.url,
method: request.method,
});
},
};
`` このコードは、受信したすべてのHTTPリクエストに対して、JSON形式のレスポンスを返すだけのシンプルな例です。env`オブジェクトを通じて、後述するKVやDurable Objectsなどのリソースにアクセスします。
wrangler.toml: このファイルはWranglerの心臓部とも言える設定ファイルです。Workersの名前、ビルド設定、バインディング、環境変数、ルート、Workers Environmentsなど、Workersの動作に関するあらゆる設定を定義します。このファイルについては、次のセクションで詳しく解説します。

プロジェクトディレクトリに移動し、コードエディタでsrc/index.tsとwrangler.tomlを開いてみてください。これで、Wranglerを使ったWorkers開発の第一歩を踏み出しました。

Wrangler.toml: 設定ファイルの徹底解説

wrangler.tomlファイルは、Cloudflare WorkersプロジェクトのWrangler設定の中心です。このファイルに、Workersの名前、ビルド方法、エッジリソースとのバインディング、環境変数、ルーティング、さらには異なるデプロイ環境ごとの設定など、プロジェクトの挙動を定義します。TOML（Tom’s Obvious, Minimal Language）形式で記述されます。

以下に、主要な設定項目とそれらの役割を詳しく解説します。

“`toml

wrangler.toml の基本的な構造と主要な設定項目

Workerの名前。CloudflareダッシュボードやCLIで表示される名前。

name = “my-workers-app”

Workersスクリプトのビルド後のファイルパスを指定。

通常は src ディレクトリにあるコードがビルドされて生成される。

デフォルトのビルド設定を使用する場合、この項目は不要。

script = “dist/worker.js”

Workersスクリプトのメインエントリポイントを指定。

src/index.ts (または .js) を使用する場合、ほとんどの場合この項目は不要。

main = “src/index.ts” # または “src/index.js”

ランタイムAPIの互換性日を指定。特定の機能を有効にするための日付。

ランタイムAPIの互換性フラグを指定。特定の実験的機能などを有効にする。

compatibility_flags = [ “streams_enable_readable_stream_async_iterator” ]

ビルド設定。カスタムビルドプロセスを指定する場合に使用。

[build]

# コマンドでビルドする場合

command = “npm run build”

# ビルド後の出力ディレクトリ

watch = [“src”] # 変更を監視するディレクトリ（ローカル開発時）

# ビルドスクリプトのタイプ (esbuild, webpack, etc.)

# packer = “esbuild”

# # esbuild オプション

# [build.upload]

# format = “modules” # または “service-worker”

# main = “src/index.ts” # ビルド対象のエントリポイント

環境変数。Workersから process.env や env オブジェクト経由でアクセスできる。

wranger secrets コマンドで設定するシークレットとは異なる。

vars = { MY_VAR = “my_value”, ANOTHER_VAR = “another_value” }

リソースバインディング。KV, DO, R2, Service Binding など、Workersが連携する外部リソースの設定。

KV Namespaces とのバインディング

[[kv_namespaces]]

binding = “MY_KV” # コード内で env.MY_KV としてアクセス

id = “YOUR_KV_NAMESPACE_ID” # Cloudflareダッシュボードまたは wrangler kv:namespace create で取得

Durable Objects とのバインディング

[[durable_objects.bindings]]

name = “MY_DO” # コード内で env.MY_DO としてアクセス

class_name = “MyDurableObject” # DOクラスの名前（コード内で定義）

# script_name = “my-other-worker” # 別Workerで定義されたDOクラスを参照する場合

R2 Buckets とのバインディング

[[r2_buckets]]

binding = “MY_R2_BUCKET” # コード内で env.MY_R2_BUCKET としてアクセス

bucket_name = “my-r2-bucket-name” # R2バケット名

Service Bindings (他の Workers へのバインディング)

[[services]]

binding = “MY_SERVICE” # コード内で env.MY_SERVICE としてアクセス

service = “other-worker-name” # 連携する他のWorkerの名前

# environment = “production” # 連携するWorkerの環境（省略時はデフォルト）

D1 Database とのバインディング

[[d1_databases]]

binding = “DB” # コード内で env.DB としてアクセス

database_name = “my-database” # D1データベース名

database_id = “YOUR_D1_DATABASE_ID” # Cloudflareダッシュボードまたは wrangler d1 create で取得

Workers AI とのバインディング

[[ai.ai_bindings]]

name = “AI” # コード内で env.AI としてアクセス

Queues とのバインディング

[[queues.producers]]

binding = “MY_QUEUE_PRODUCER” # コード内で env.MY_QUEUE_PRODUCER としてアクセス

queue = “my-queue-name” # キュー名

[[queues.consumers]]

queue = “my-queue-name” # キュー名

event_handler = “src/consumer.ts” # コンシューマーコードのエントリポイント

デプロイルート。WorkersがどのURLパターンで実行されるかを定義。

[[routes]]

pattern = “my-workers-app.example.com/” # または “.example.com/api/*” など

zone_id = “YOUR_ZONE_ID” # ゾーンID（ダッシュボードまたは wrangler zones で取得）

custom_domain = true # true の場合 pattern はカスタムドメインとして扱われる

Workers Sites 設定。静的サイトホスティングに使用。

[site]

bucket = “./dist” # 静的ファイルが含まれるディレクトリ

# entry-point = “workers-site” # Workers Sites 用の Workers コードの場所（デフォルトは workers-site ディレクトリ）

# include = [“assets/*”] # 含めるファイルパターン

# exclude = [“build/*”] # 除外するファイルパターン

Environments (異なる環境ごとの設定)

[environments]

[environments.staging]

name = “my-workers-app-staging” # ステージング環境の名前

# 特定の環境でのみ上書きしたい設定を記述

# vars = { ENV = “staging” }

# [[environments.staging.kv_namespaces]]

# binding = “MY_KV”

# id = “YOUR_STAGING_KV_NAMESPACE_ID”

[environments.production]

# name は省略可。省略時はデフォルト名 (my-workers-app) を使用。

# vars = { ENV = “production” }

# [[environments.production.kv_namespaces]]

# binding = “MY_KV”

# id = “YOUR_PRODUCTION_KV_NAMESPACE_ID”

レート制限設定

[limits]

# 同時リクエスト制限

concurrent_requests = 1000

Wasm モジュールの設定

[[wasm_modules]]

binding = “MY_WASM” # コード内で env.MY_WASM としてアクセス

module = “./my_module.wasm” # Wasm ファイルのパス

テキストアセットのバインディング

[[text_blobs]]

binding = “MY_TEXT” # コード内で env.MY_TEXT としてアクセス

path = “./my_text_file.txt” # テキストファイルのパス

データアセットのバインディング (バイナリデータなど)

[[data_blobs]]

binding = “MY_DATA” # コード内で env.MY_DATA としてアクセス

path = “./my_data_file.bin” # バイナリファイルのパス

tail workers 設定

[tail_consumers]

url = “https://my-log-forwarding-service.example.com/log” # ログを転送するエンドポイント

service = “my-other-worker” # ログを処理する他のWorkerの名前

“`

主要な設定項目の詳細解説

name: Workersスクリプトの名前を定義します。これはCloudflareダッシュボードやWranglerコマンドで使用される識別子です。プロジェクトディレクトリ名と合わせるのが一般的ですが、必須ではありません。
script / main:
- scriptは、ビルド済みの単一ファイル Workersの場合にそのパスを指定します。
- mainは、ESモジュール形式で記述されたWorkersのエントリポイントを指定します。TypeScriptを使用している場合や、format = "modules"でビルドする場合はこちらを使用します。Wranglerのデフォルトビルド設定を使用している場合、mainは通常src/index.ts（または.js）を指し、明示的に設定する必要はありません。
compatibility_date / compatibility_flags: Workersランタイムの挙動は、時間の経過とともに新しい機能の追加や変更が行われます。これらの設定は、Workersスクリプトがどの時点のランタイム挙動を基準とするかを指定します。新しい機能や変更を取り込むためには、compatibility_dateを最新の日付に更新し、必要に応じてcompatibility_flagsを追加します。Cloudflareのドキュメントで最新の日付とフラグを確認してください。
build: デフォルトのビルドプロセス（esbuildを使用）以外のカスタムビルドプロセスが必要な場合に設定します。commandで任意のビルドコマンド（例: npm run build）を指定したり、upload.formatで生成されるスクリプトの形式（modulesまたはservice-worker）を指定したりできます。TypeScriptを使用している場合は、Wranglerが自動的にTypeScriptをビルドしてくれるため、多くの場合このセクションを明示的に設定する必要はありません。
vars: 環境変数を定義します。ここに設定された値は、Workersスクリプト内でenv.<変数名>としてアクセスできます。APIキーなどの機密情報には使用せず、設定値（例: サービスのエンドポイントURL、環境タイプなど）に使用します。機密情報は後述するsecretsを使用します。
リソースバインディング (kv_namespaces, durable_objects, r2_buckets, services, d1_databases, ai.ai_bindings, queues): Workersが外部のリソースと連携するために必要な設定です。
- それぞれの設定項目は配列になっており、複数のリソースをバインドできます。
- bindingは、Workersコード内でそのリソースにアクセスするために使用する変数名です（例: env.MY_KV）。
- id、bucket_name、service、database_id などは、バインドする実際のリソースの識別子を指定します。これらのリソースは、CloudflareダッシュボードまたはWranglerコマンドで事前に作成しておく必要があります。
- Durable Objectsの場合は、バインドするDOの名前（name）と、対応するDOクラスの名前（class_name）を指定します。
routes: このWorkersスクリプトをどのURLパターンで実行するかを定義します。一つのWorkersに複数のルートを設定したり、複数のWorkersで同じルートを異なるパターンで処理させたりできます。patternにURLパターン（例: "*/api/*"）を、zone_idにそのパターンが属するCloudflareゾーンのIDを指定します。custom_domain = trueを設定すると、パターンをカスタムホスト名として扱うことができます。
site: Workers Sites機能を使用して静的サイトをホストする場合に設定します。bucketには、静的ファイル（HTML, CSS, JS, 画像など）が含まれるディレクトリのパスを指定します。Wranglerはこのディレクトリの内容をWorkers KVにアップロードし、専用のWorkersスクリプト（Workers Sitesテンプレート）と連携して静的コンテンツを配信します。
environments: 異なるデプロイ環境（例: staging, production）ごとに設定を分けるために使用します。[environments.<環境名>]セクションの下に、デフォルト設定を上書きしたい項目（name, vars, バインディングなど）を記述します。これにより、例えばステージング環境ではテスト用のKV名前空間を使用し、プロダクション環境では本番用のKV名前空間を使用するといった切り替えが容易になります。wrangler deploy --env <環境名>のようにコマンドで環境を指定してデプロイします。
limits: Workersの実行に関する制限を設定できます。例えば、concurrent_requestsで同時リクエスト数を制限できます。
wasm_modules, text_blobs, data_blobs: WebAssemblyモジュール、テキストファイル、バイナリファイルなどのアセットをWorkersにバインドし、コード内からアクセスできるようにします。
tail_consumers: Workersの実行ログを他のサービスやWorkerに転送するための設定です。

wrangler.tomlは、Workers開発の柔軟性と強力さを支える重要な要素です。これらの設定項目を理解し、プロジェクトのニーズに合わせて適切に構成することが、Wranglerを効果的に活用する鍵となります。

ローカル開発環境 (`wrangler dev`): Miniflareからworkerdへ

Cloudflare Workersの開発において、最も重要な機能の一つが高速なローカル開発環境です。Wranglerのwrangler devコマンドは、Workersをローカルマシン上で実行し、コードの変更をリアルタイムで反映することで、迅速なイテレーション開発を可能にします。

かつてWranglerのローカル開発環境はMiniflareというNode.jsベースのエミュレーターを使用していましたが、現在はCloudflare Workersの実際のランタイムであるworkerd（オープンソース化されたCloudflare Workers Runtime）を利用しています。これにより、ローカル環境と本番エッジ環境との差異が最小限に抑えられ、より信頼性の高いテストが可能になりました。

`wrangler dev` コマンドの使い方

プロジェクトのルートディレクトリ（wrangler.tomlがあるディレクトリ）で、以下のコマンドを実行します。

bash wrangler dev

このコマンドは、Workersスクリプトをビルドし、ローカルのHTTPサーバーを起動します。通常、localhost:8787などのアドレスでWorkerが実行されます。ターミナルには、Workerが実行されているローカルURLが表示されます。

ブラウザやcurlなどのツールでそのURLにアクセスすると、ローカルで実行されているWorkersがリクエストを処理します。

bash curl http://localhost:8787/

ホットリロード

wrangler devを実行した状態でWorkersのコード（src/index.tsなど）を変更して保存すると、Wranglerは自動的にコードを再ビルドし、実行中のローカルWorkerを更新します。これにより、コードを変更するたびに手動で再起動する必要がなく、開発サイクルが大幅に短縮されます。

`workerd` (Cloudflare Workers Runtime)

wrangler devの背後では、Cloudflare Workersの実際のランタイムであるworkerdが動作しています。これにより、以下のメリットが得られます。

高い忠実度: ローカル環境での実行挙動が本番エッジ環境に非常に近いため、デプロイ後の予期しないエラーが発生しにくくなります。
Workers APIの完全なサポート: FetchEvent, ExecutionContextなどの標準的なWorkers APIだけでなく、KV, Durable Objects, R2などのストレージAPI、Service Bindings、Queuesなど、Cloudflare Workers Runtimeが提供するほぼすべてのAPIがローカルでエミュレーションまたは利用可能です。
高速な実行: workerdはC++で実装されており、非常に高速に動作します。

ローカルでの各種リソースのエミュレーション

wrangler devは、wrangler.tomlで設定された各種リソースバインディングをローカルでエミュレートする機能も提供します。これにより、Workersコードがストレージや他のサービスと連携する部分も、ローカル環境でテストできます。

KV Namespaces: wrangler.tomlで設定したKVバインディングは、ローカルでは一時的なファイルシステム（またはインメモリ）ストアとしてエミュレートされます。ローカル開発中にKVに書き込んだデータは、開発サーバーを停止すると失われます。永続化したい場合は、ローカルのファイルパスを指定することも可能です。
Durable Objects: Durable Objectsもローカルでエミュレートされます。DOインスタンスの状態はローカルファイルに保存されるため、wrangler devを再起動しても状態は維持されます。
R2 Buckets: R2もローカルファイルシステムでエミュレートされます。ファイルのアップロード、ダウンロード、削除などの操作をローカルでテストできます。
Service Bindings: 他のWorkersへのService Bindingsも、ローカルで実行中の他のWorkersインスタンス（別のポートでwrangler devを実行している場合）や、リモートのWorkersにバインドしてテストできます。
D1 Database: D1もローカルのSQLiteデータベースファイルでエミュレートされます。SQLクエリの実行などをローカルでテストできます。
Queues: Cloudflare Queuesの操作もローカルでエミュレートされます。メッセージの送信・受信をテストできます。

これらのエミュレーション機能により、外部サービスに依存することなく、Workersアプリケーション全体をローカルで開発・テストすることが可能です。

オプション (`wrangler dev --<option>`)

wrangler devコマンドには、開発体験をさらにカスタマイズするための様々なオプションがあります。

--port <ポート番号>: ローカルサーバーのポート番号を指定します。（デフォルト: 8787）
--host <ホスト名>: ローカルサーバーのホスト名を指定します。（デフォルト: localhost）
--ip <IPアドレス>: バインドするIPアドレスを指定します。（デフォルト: 127.0.0.1）
--env <環境名>: wrangler.tomlで定義された特定の環境（例: staging）の設定を使用してローカル実行します。
--remote: ローカルのコードをCloudflareのエッジに一時的にデプロイし、そこで実行します。これは、ローカルエミュレーションでは再現できない、本番に近い環境でのテストに役立ちます。ただし、実行は実際のCloudflareアカウントで行われるため、料金が発生する可能性があります。
--log-request / --log-response: リクエスト/レスポンスヘッダーとボディをログに出力します。デバッグに便利です。
--vars <JSON文字列またはファイルパス>: コマンドラインから一時的に環境変数を設定します。wrangler.tomlのvars設定を上書きします。
--inspect / --inspect-brk: Node.jsのインスペクターを有効にし、デバッガーをアタッチできるようにします。Workersコードをステップ実行する際に便利です。

例: ステージング環境の設定で、ポート3000でローカル実行し、リモートモードを使用する場合。

bash wrangler dev --env staging --port 3000 --remote

ローカル開発環境は、Workers開発の効率を左右する最も重要な要素です。wrangler devとworkerdの機能を最大限に活用することで、迅速かつ信頼性の高い開発が可能になります。

各種リソースとの連携 (KV, DO, R2, Service Bindings, D1)

Cloudflare Workersは、単体で動作するだけでなく、Cloudflareが提供する様々なエッジサービスと連携することで、より高度でステートフルなアプリケーションを構築できます。Wranglerはこれらのリソースとのバインディング設定を容易にし、ローカル開発環境でのエミュレーションを提供します。

1. キーバリューストア (KV)

Cloudflare KVは、エッジで利用可能な高速なキーバリューストアです。設定データ、セッション情報、静的アセットのキャッシュなど、低レイテンシでの読み書きが必要なデータに適しています。

Wranglerでの設定:

wrangler.tomlに[[kv_namespaces]]セクションを追加します。

toml [[kv_namespaces]] binding = "MY_KV_DATA" # コード内で env.MY_KV_DATA としてアクセス id = "YOUR_KV_NAMESPACE_ID" # 既存のKV名前空間のID

KV名前空間は事前に作成が必要です。wrangler kv:namespace create <名前>コマンドを使用するか、Cloudflareダッシュボードで作成します。

“`bash
wrangler kv:namespace create my-app-kv

出力例:

🌍 Creating namespace “my-app-kv”

✨ Success! Created namespace “my-app-kv”

Add the following to your wrangler.toml:

[[kv_namespaces]]

binding = “MY_APP_KV” # <– Use this name in your Worker

id = “” # <– Add this ID to your wrangler.toml

“`

生成されたidをwrangler.tomlにコピーします。

Workersコードでの利用:

“`typescript
export interface Env {
MY_KV_DATA: KVNamespace; // wrangler.toml の binding 名と一致
}

export default {
async fetch(request: Request, env: Env): Promise {
const key = “greeting”;
const value = await env.MY_KV_DATA.get(key); // データの取得

if (value === null) {
  await env.MY_KV_DATA.put(key, "Hello, KV!"); // データの書き込み
  return new Response("Value set in KV.");
} else {
  return new Response(`Value from KV: ${value}`);
}

},
};
“`

ローカルエミュレーション:

wrangler devを実行すると、MY_KV_DATAバインディングはローカルのファイルシステム上でエミュレートされます。

bash wrangler dev

デフォルトでは、ローカルでKVに保存したデータはwrangler devを停止すると消えます。永続化したい場合は、wrangler.tomlの[[kv_namespaces]]設定にpreview_idやpersist_toオプションを追加します。

2. Durable Objects (DO)

Cloudflare Durable Objectsは、エッジ環境でステートフルなアプリケーションを構築するための機能です。WebSocketサーバー、共同編集ドキュメント、ゲームサーバーなど、特定の「オブジェクト」（IDで識別される単一インスタンス）の状態を維持する必要があるユースケースに最適です。

Wranglerでの設定:

Durable ObjectsクラスをWorkersコード内で定義します。

“`typescript
// src/durable_objects.ts
export class MyDurableObject {
private state: number;
constructor(state: DurableObjectState) {
this.state = 0;
state.blockConcurrencyWhile(async () => {
this.state = (await state.storage.get(“state”)) || 0;
});
}

async fetch(request: Request) {
const url = new URL(request.url);
const action = url.searchParams.get(“action”);
```
if (action === "increment") {
  this.state++;
  await this.state.storage.put("state", this.state);
  return new Response(`State incremented to ${this.state}`);
} else if (action === "get") {
  return new Response(`Current state: ${this.state}`);
} else {
  return new Response("Invalid action");
}
```
}
}
“`
wrangler.tomlに[[durable_objects.bindings]]セクションを追加し、DOクラスをバインドします。

“`toml
[[durable_objects.bindings]]
name = “MY_DURABLE_OBJECT” # コード内で env.MY_DURABLE_OBJECT としてアクセス
class_name = “MyDurableObject” # 上記で定義したDOクラスの名前

script_name = “durable-object-worker” # DOクラスが別のWorkerで定義されている場合

“`
メインのWorkersスクリプトからDOにアクセスします。

“`typescript
// src/index.ts
export interface Env {
MY_DURABLE_OBJECT: DurableObjectNamespace; // wrangler.toml の name と一致
}

export default {
async fetch(request: Request, env: Env): Promise {
const url = new URL(request.url);
const objectId = env.MY_DURABLE_OBJECT.idFromName(“my_unique_id”); // DOインスタンスをIDで取得
const stub = env.MY_DURABLE_OBJECT.get(objectId); // Stubを取得
```
// Stub を通じて DO インスタンスにリクエストを送信
return stub.fetch(url);
```
},
};
“`

ローカルエミュレーション:

wrangler devはDurable Objectsもローカルでエミュレートします。DOの状態はローカルファイルに保存されるため、wrangler devを再起動しても状態は維持されます。

bash wrangler dev

ローカルでのDOの永続化ディレクトリは、デフォルトで.wrangler/state/v3/durableobjectsなどに作成されます。

3. R2 (Object Storage)

Cloudflare R2は、S3互換のオブジェクトストレージサービスです。静的アセット、バックアップ、ログなどの大量の非構造化データを保存するのに適しています。データ転送量に対する課金がないのが大きな特徴です。

Wranglerでの設定:

wrangler.tomlに[[r2_buckets]]セクションを追加します。

toml [[r2_buckets]] binding = "MY_R2_BUCKET" # コード内で env.MY_R2_BUCKET としてアクセス bucket_name = "my-r2-bucket-name" # 既存のR2バケット名

R2バケットも事前に作成が必要です。wrangler r2 bucket create <バケット名>コマンドを使用するか、Cloudflareダッシュボードで作成します。

“`bash
wrangler r2 bucket create my-r2-bucket-name

出力例:

🌎 Creating bucket “my-r2-bucket-name”

✨ Success! Created bucket “my-r2-bucket-name”

Add the following to your wrangler.toml:

[[r2_buckets]]

binding = “MY_BUCKET” # <– Use this name in your Worker

bucket_name = “my-r2-bucket-name”

“`

Workersコードでの利用:

“`typescript
export interface Env {
MY_R2_BUCKET: R2Bucket; // wrangler.toml の binding 名と一致
}

export default {
async fetch(request: Request, env: Env): Promise {
const url = new URL(request.url);
const key = url.pathname.slice(1); // パスをオブジェクトキーとして使用

if (request.method === "PUT") {
  // オブジェクトのアップロード
  await env.MY_R2_BUCKET.put(key, request.body);
  return new Response(`PUT ${key} successful.`);
} else if (request.method === "GET") {
  // オブジェクトのダウンロード
  const object = await env.MY_R2_BUCKET.get(key);
  if (object === null) {
    return new Response("Object not found", { status: 404 });
  }
  return new Response(object.body, { headers: object.httpMetadata });
}

return new Response("Method not allowed", { status: 405 });

},
};
“`

ローカルエミュレーション:

wrangler devはR2バケットもローカルファイルシステムでエミュレートします。デフォルトでは.wrangler/state/v3/r2ディレクトリにファイルが保存されます。

bash wrangler dev

4. Service Bindings

Service Bindingsを使用すると、あるWorkersスクリプトから別のWorkersスクリプトを呼び出すことができます。これは、モノリシックなWorkersをマイクロサービスに分割したり、共通機能を別のWorkersとして提供したりする場合に便利です。

Wranglerでの設定:

wrangler.tomlに[[services]]セクションを追加します。

“`toml
[[services]]
binding = “MY_OTHER_WORKER” # コード内で env.MY_OTHER_WORKER としてアクセス
service = “name-of-other-worker” # 連携する他のWorkersの名前

environment = “production” # 連携するWorkersの特定の環境を指定する場合

“`

name-of-other-workerは、連携したいWorkersのwrangler.tomlで定義されたnameです。

Workersコードでの利用:

“`typescript
export interface Env {
MY_OTHER_WORKER: Fetcher; // wrangler.toml の binding 名と一致
}

export default {
async fetch(request: Request, env: Env): Promise {
// MY_OTHER_WORKER サービスにリクエストを転送または送信
const response = await env.MY_OTHER_WORKER.fetch(request);

// または、新しいリクエストを作成して送信
// const newRequest = new Request("https://api.example.com/internal", {
//   headers: { "X-Internal-Auth": "secret" },
// });
// const response = await env.MY_OTHER_WORKER.fetch(newRequest);

return response; // 他のWorkerからの応答を返す

},
};
“`

Fetcherは、Workers Runtimeが提供するService Binding用のインターフェースです。

ローカルエミュレーション:

ローカル開発時、wrangler devはデフォルトでリモートのCloudflare環境にあるサービスにバインドしようとします。ローカルで実行中の他のWorkersインスタンスにバインドしたい場合は、そのWorkersもwrangler devで起動し、必要に応じてローカルでService Bindingをエミュレーションする設定を行う必要があります。

5. D1 (SQLite Database)

Cloudflare D1は、エッジで動作するリレーショナルデータベースです。SQLiteをベースとしており、Workersから低レイテンシでアクセスできます。

Wranglerでの設定:

D1データベースを事前に作成します。wrangler d1 create <データベース名>コマンドを使用します。

“`bash
wrangler d1 create my-app-db

出力例:

🌀 Creating D1 database “my-app-db” on the “us-east1” location…

✅ Created D1 database “my-app-db”!

To get started, add the following to your wrangler.toml file:

[[d1_databases]]

binding = “DB” # <— This is the name of the binding.

database_name = “my-app-db”

database_id = “” # <— Copy this ID to your wrangler.toml

“`
生成されたdatabase_idをwrangler.tomlにコピーします。

toml [[d1_databases]] binding = "DB" # コード内で env.DB としてアクセス database_name = "my-app-db" # データベース名 database_id = "YOUR_D1_DATABASE_ID" # 作成時に生成されたID

Workersコードでの利用:

“`typescript
export interface Env {
DB: D1Database; // wrangler.toml の binding 名と一致
}

export default {
async fetch(request: Request, env: Env): Promise {
const { pathname } = new URL(request.url);

if (pathname === "/api/users") {
  const { results } = await env.DB.prepare("SELECT * FROM users").all();
  return Response.json(results);
}

if (pathname === "/api/users/create" && request.method === "POST") {
  const { name } = await request.json();
  const { success } = await env.DB.prepare("INSERT INTO users (name) VALUES (?)").bind(name).run();

  if (success) {
    return new Response("User created", { status: 201 });
  } else {
    return new Response("Failed to create user", { status: 500 });
  }
}

return new Response("Not Found", { status: 404 });

},
};
“`

ローカルエミュレーション:

wrangler devはD1データベースもローカルのSQLiteファイルでエミュレートします。デフォルトでは.wrangler/state/v3/d1ディレクトリにデータベースファイルが作成されます。ローカルで開発中にテーブルを作成したりデータを挿入したりできます。

bash wrangler dev

ローカル開発中にSQLスキーマを適用するには、wrangler d1 execute <データベース名> --local --file=<スキーマファイル>コマンドを使用します。

これらのリソース連携機能をWrangler経由で設定し、ローカルでエミュレーションすることで、Workersをより複雑で機能的なアプリケーションへと発展させることが可能になります。Wranglerのローカル開発環境は、これらのエッジサービスとの統合開発・テストにおいて非常に強力な役割を果たします。

シークレット管理 (`wrangler secret`)

APIキー、データベース認証情報、外部サービスのシークレットなど、アプリケーションで使用する機密情報は、コードや設定ファイルに直接記述すべきではありません。Wranglerは、Cloudflareが提供するシークレット管理機能をコマンドラインから操作することで、機密情報を安全にWorkersにバインディングする手段を提供します。

`wrangler secret` コマンド

wrangler secretコマンドは、Cloudflareアカウントに安全にシークレットを保存し、Workersスクリプトから環境変数としてアクセスできるようにします。

シークレットの設定:

シークレットを設定するには、以下のコマンドを使用します。

bash wrangler secret put MY_API_KEY

このコマンドを実行すると、シークレットの値を入力するように求められます。入力された値は暗号化されてCloudflareのシステムに保存されます。

bash $ wrangler secret put MY_API_KEY 🔑 Enter a secret value for MY_API_KEY: (Paste your secret and press Enter) ✨ Successfully uploaded MY_API_KEY

--env <環境名>オプションを使用することで、特定の環境にシークレットを設定することも可能です。

bash wrangler secret put DATABASE_URL --env staging

シークレットの一覧表示:

設定済みのシークレット名を確認するには、以下のコマンドを使用します。

bash wrangler secret list

bash $ wrangler secret list ✨ Successfully fetched secrets MY_API_KEY DATABASE_URL (set for environment: staging)

シークレットの削除:

シークレットを削除するには、以下のコマンドを使用します。

“`bash
wrangler secret delete MY_API_KEY

特定の環境のシークレットを削除

wrangler secret delete DATABASE_URL –env staging
“`

`wrangler.toml`での設定とコードでの利用

wrangler secret putで設定したシークレットは、wrangler.tomlに明示的に記述する必要はありません。デプロイ時にWranglerが自動的にCloudflareのシークレットとWorkersを関連付けてくれます。

Workersコード内からは、wrangler.tomlのvarsで設定した環境変数と同様に、env.<シークレット名>としてアクセスできます。

“`typescript
export interface Env {
MY_API_KEY: string; // シークレット名と一致
}

export default {
async fetch(request: Request, env: Env): Promise {
const apiKey = env.MY_API_KEY; // シークレットにアクセス

if (!apiKey) {
  return new Response("API Key not configured", { status: 500 });
}

// APIキーを使用して外部サービスにリクエストを送信するなどの処理
// const response = await fetch("https://api.example.com/data", {
//   headers: { "Authorization": `Bearer ${apiKey}` }
// });

return new Response(`Using API Key: ${apiKey.substring(0, 4)}...`); // 安全のために一部のみ表示

},
};
“`

Wranglerがデプロイを行う際、Cloudflareは保存されているシークレットの値をWorkersインスタンスに安全に注入します。コードが直接シークレットの値を扱わないため、コードの漏洩リスクを低減できます。

ローカル開発でのシークレット

wrangler devでローカル開発を行う場合、デフォルトではCloudflareに保存されているシークレットにはアクセスできません。ローカルでシークレットが必要な場合は、いくつかの方法があります。

.dev.vars ファイル: プロジェクトのルートディレクトリに.dev.varsというファイルを作成し、KEY=VALUE形式でローカル開発用のシークレットを記述します。このファイルはGit管理から除外（.gitignoreに追加）すべきです。

“`

.dev.vars

MY_API_KEY=fake_local_api_key_value
“`

wrangler devは自動的に.dev.varsを読み込み、環境変数としてWorkersコードに渡します。
コマンドラインオプション: wrangler dev --varsオプションを使用して一時的にシークレットを渡します。（ただし、これは開発時の一時的なテスト向けで、機密情報を直接コマンドラインに渡すのは非推奨です）
リモートモード (--remote): wrangler dev --remoteを使用すると、コードは一時的にCloudflareにデプロイされて実行されるため、Cloudflareに設定済みのシークレットにアクセスできます。ただし、これは実際の料金が発生する可能性があります。

セキュリティ上の理由から、ローカル開発中はモック値やテスト用の認証情報を使用し、本番の機密情報にはアクセスしないようにするのがベストプラクティスです。

wrangler secretコマンドと.dev.varsファイルを組み合わせることで、本番環境ではCloudflareのシークレットストアを使用し、ローカル開発環境では安全にテスト用の値を使用するというワークフローを構築できます。

ビルドプロセスとカスタム設定

Cloudflare WorkersはJavaScriptやWebAssemblyで動作しますが、特にTypeScriptを使用する場合や、複数のファイルに分割してコードを記述している場合、あるいはRustなどの他の言語からWebAssemblyにコンパイルする場合は、デプロイ前にコードを一つのファイルにバンドル（ビルド）する必要があります。Wranglerは強力なビルド機能を内蔵しており、ほとんどのユースケースに対応できます。

Wranglerのデフォルトビルド

Wranglerは、内部的にesbuildという高速なJavaScript/TypeScriptバンドラーを使用しています。wrangler initでTypeScriptプロジェクトを作成した場合、Wranglerは自動的にesbuildを使ってTypeScriptコードをJavaScriptにトランスパイルし、Workersランタイムに適した形式にバンドルします。

このデフォルトのビルドプロセスは、多くの一般的なWorkersプロジェクトで十分です。wrangler.tomlに特別な設定を記述する必要はありません。

TypeScript: .tsファイルを自動的に処理します。
ES Modules: import/export構文を解決し、単一ファイルにバンドルします。
Workers Runtime API: cloudflare:kv-namespaceなどの特殊なインポートを適切に扱います。
Source Maps: デバッグ用のソースマップも生成できます。

カスタムビルド設定 (`wrangler.toml`の `[build]`)

より複雑なビルド要件がある場合や、Webpack、Rollupなどの別のバンドラーを使用したい場合は、wrangler.tomlの[build]セクションでカスタムビルドプロセスを設定できます。

“`toml
[build]

ビルドコマンドを指定

command = “npm run build”

変更を監視するディレクトリ（ローカル開発時）

watch = [“src”, “scripts”]

ビルド後の出力ディレクトリを指定

これは wrangler のデフォルトビルドが使用される場合に適用されることが多い

dest = “dist”

[build.upload]

生成されるスクリプトの形式を指定 (modules または service-worker)

ビルド後のエントリポイントファイルを指定 (format = “modules” の場合)

command を使用する場合は、command が生成する最終ファイルのパスを指定

main = “dist/worker.js”

“`

command: Wranglerがビルドを実行する際に実行するシェルコマンドを指定します。例えば、npm run buildを指定し、package.jsonのscriptsでWebpackやesbuildのコマンドを定義することで、完全にカスタムなビルドパイプラインを構築できます。
json // package.json { "scripts": { "build": "webpack --config webpack.config.js" } }
watch: wrangler devでローカル開発を行う際に、ファイル変更を監視してホットリロードをトリガーする対象ディレクトリを指定します。デフォルトではsrcなどが含まれますが、追加したいディレクトリがあればここに指定します。
build.upload.format: デプロイされるWorkersスクリプトの形式を指定します。
- "modules": ESモジュール形式。最新のWorkers機能（Top-Level Await, Durable Objectsなど）を利用するために推奨されます。
- "service-worker": 以前のService Worker形式。古いWorkersや特定のユースケースで使用されることがありますが、新しいプロジェクトでは通常modulesを使用します。
build.upload.main: format = "modules"の場合に、バンドルされたWorkersスクリプトのエントリポイントとなるファイルのパスを指定します。commandでカスタムビルドを行っている場合は、そのコマンドが生成する最終的なエントリポイントファイルを指すように設定します。

WebAssembly (Wasm) との連携

Cloudflare WorkersはWebAssemblyの実行もサポートしています。パフォーマンスが重要な処理や、既存のC/C++/Rustなどのコードを再利用したい場合に便利です。WranglerはWasmモジュールとの連携もサポートしています。

Rustなどの言語でコードを記述し、WebAssemblyにコンパイルします。

“`bash

Rust の場合

cargo install wasm-pack
wasm-pack build –target no-modules –out-dir wasm –scope my-app
`` これにより、wasm/my_app_bg.wasm` のようなWasmファイルが生成されます。
wrangler.tomlでWasmモジュールをバインドします。

toml [[wasm_modules]] binding = "MY_WASM_MODULE" # コード内で env.MY_WASM_MODULE としてアクセス module = "./wasm/my_app_bg.wasm" # 生成されたWasmファイルのパス
Workersコード内でWasmモジュールをインポートし、利用します。

“`typescript
// src/index.ts
import wasm from ‘./wasm/my_app_bg.wasm’; // WASM ファイルをインポート (esbuildなどが処理)
// import { myFunction } from ‘./wasm’; // wasm-pack が生成した JS ラッパーをインポート

export interface Env {
MY_WASM_MODULE: WebAssembly.Module; // wrangler.toml の binding 名と一致
}

export default {
async fetch(request: Request, env: Env): Promise {
// WASM バインディングを使用する場合
const instance = new WebAssembly.Instance(env.MY_WASM_MODULE, { / imports / });
// instance.exports.my_function();
```
// wasm-pack が生成した JS ラッパーを使用する場合 (デフォルトビルドの場合)
// const result = myFunction();

return new Response("Wasm executed.");
```
},
};
`` Wranglerのデフォルトビルド（esbuild）は、コード内で直接Wasmファイルをimportする構文（import wasm from ‘./module.wasm’）もサポートしており、自動的にWasmファイルをバンドルしてくれます。[[wasm_modules]]は、Wasmファイルを環境変数のようにバインドする場合に使用します。どちらの方法を使用するかは、プロジェクトの構成によります。wasm-pack`のようなツールを使用する場合は、JSラッパー経由でインポートする方法が一般的です。

Wranglerのビルド機能は非常に強力で柔軟です。デフォルト設定で多くのプロジェクトに対応しつつ、必要に応じてカスタムビルドパイプラインを簡単に組み込むことができます。Wasmとの連携もスムーズに行え、Workersの表現力をさらに広げます。

デプロイ戦略 (`wrangler deploy`): Environmentsとルーティング

Wranglerの最も重要な機能の一つは、開発したWorkersスクリプトをCloudflareのエッジネットワークにデプロイすることです。wrangler deployコマンドを使用することで、このプロセスを簡単かつ信頼性高く実行できます。

基本的なデプロイ

プロジェクトのルートディレクトリで、以下のコマンドを実行します。

bash wrangler deploy

このコマンドは、以下の処理を行います。

wrangler.tomlの設定に基づいてWorkersスクリプトをビルドします。
ビルドされたスクリプトをCloudflareにアップロードします。
wrangler.tomlで定義された設定（名前、バインディング、ルートなど）をCloudflareアカウントに適用または更新します。
デプロイが完了すると、スクリプトが有効化され、関連付けられたルートでアクセス可能になります。

初めてデプロイする場合、Cloudflareアカウント上にWorkersスクリプトや関連リソース（KV, DO, R2など）が作成されます。2回目以降のデプロイでは、既存のリソースが更新されます。

Environments (環境) を使用したデプロイ

多くのアプリケーション開発では、開発環境、ステージング環境、本番環境など、複数の環境を使い分けることが一般的です。各環境では、異なるAPIエンドポイント、データベース、設定値などを使用したい場合があります。WranglerのEnvironments機能は、このニーズに対応します。

wrangler.tomlの[environments]セクションで、異なる環境ごとの設定を定義します。

“`toml

デフォルト設定 (多くの場合 production 環境に相当)

name = “my-workers-app”

… その他のデフォルト設定 …

[environments]
[environments.staging]
name = “my-workers-app-staging” # ステージング用の名前 (オプション)
# ステージング環境で上書きしたい設定
vars = { ENV = “staging”, API_ENDPOINT = “https://api.staging.example.com” }
[[environments.staging.kv_namespaces]]
binding = “MY_KV”
id = “YOUR_STAGING_KV_NAMESPACE_ID” # ステージング用のKV ID

[environments.production]
# name = “my-workers-app” # デフォルト名と同じなので省略可
vars = { ENV = “production”, API_ENDPOINT = “https://api.production.example.com” }
[[environments.production.kv_namespaces]]
binding = “MY_KV”
id = “YOUR_PRODUCTION_KV_NAMESPACE_ID” # 本番用のKV ID
“`

異なる環境にデプロイするには、--envオプションを使用します。

“`bash

ステージング環境にデプロイ

wrangler deploy –env staging

本番環境にデプロイ (environments.production セクションに name がない場合はデフォルト名を使用)

wrangler deploy –env production # environments.production セクションに name が my-workers-app であれば、これはデフォルトの deploy と同じ

environments.production セクションで別の name を指定している場合はその名前でデプロイされる

“`

wrangler deploy --env stagingを実行すると、[environments.staging]セクションで定義された設定が、デフォルト設定を上書きして適用されます。例えば、デプロイされるWorkersの名前はmy-workers-app-stagingとなり、env.ENVの値は"staging"、env.MY_KVは指定されたステージング用のKV名前空間を指すようになります。

Environments機能を使うことで、単一のwrangler.tomlファイルで複数の環境設定を一元管理し、デプロイプロセスを簡素化できます。

ルーティング (`[[routes]]`)

WorkersスクリプトをどのURLパターンで実行するかは、wrangler.tomlの[[routes]]セクションで定義します。デプロイ時にこの設定がCloudflareに適用され、指定したパターンに一致するリクエストがWorkersにルーティングされるようになります。

“`toml
name = “my-api-worker”

…その他の設定…

[[routes]]
pattern = “api.example.com/users/*” # このパターンに一致するリクエストを Worker にルーティング
zone_id = “YOUR_ZONE_ID” # example.com ゾーンの ID
custom_domain = true # pattern がカスタムドメインである場合

[[routes]]
pattern = “example.com/legacy/users/*” # 同じ Worker に別のパターンも紐付け可能
zone_id = “YOUR_ZONE_ID”
custom_domain = false # example.com はこのゾーンのドメインなので custom_domain は false (または省略)

[[routes]]
pattern = “another-zone.com/api/*” # 別のゾーンにも紐付け可能
zone_id = “YOUR_ANOTHER_ZONE_ID” # another-zone.com ゾーンの ID
custom_domain = false
“`

pattern: Workersがリクエストを処理するURLパターンを指定します。ワイルドカード（*）を使用できます。
zone_id: そのパターンが属するCloudflareゾーンのIDを指定します。ゾーンIDはCloudflareダッシュボードのゾーンの概要ページや、wrangler zones listコマンドで確認できます。
custom_domain: patternがCloudflareに管理されているゾーン内のドメインではなく、カスタムドメインとして扱われる場合にtrueを設定します。（例: pattern = "my-app.my-company.com/*"で、my-company.comは別のCloudflareアカウントで管理されている場合など）。

デプロイ時、Wranglerはこのroutes設定をCloudflareのAPIに送信し、ゾーンの設定を更新します。

その他のデプロイ関連コマンド

wrangler rollback: 最新のデプロイバージョンに戻します。
wrangler publish: wrangler deployの古いエイリアスですが、非推奨です。wrangler deployを使用してください。
wrangler delete: デプロイ済みのWorkersスクリプトをCloudflareから削除します。（注意して使用してください）

デプロイはWorkers開発プロセスの最終段階ですが、WranglerのEnvironmentsとルーティング機能により、複雑なアプリケーションのデプロイメント戦略を柔軟かつ効率的に管理できます。CI/CDパイプラインにWranglerのデプロイコマンドを組み込むことで、自動化された信頼性の高いデプロイを実現できます。

Workers Sitesの利用

Cloudflare Workers Sitesは、WorkersとWorkers KVを組み合わせて、静的サイトを高速かつ効率的に配信するための機能です。ビルドされた静的サイトのファイル（HTML, CSS, JS, 画像など）をKVに保存し、Workersスクリプトがリクエストパスに基づいて適切なファイルをKVから取得して配信します。WranglerはWorkers Sitesプロジェクトのビルドとデプロイを効率化します。

Workers Sitesの仕組み

開発者はHTML、CSS、JavaScriptなどで静的サイトを作成し、ビルドツール（Webpack, Parcel, Hugo, Jekyllなど）で配信可能な状態にします。
Wranglerがビルドされた静的サイトのファイルをCloudflare Workers KVにアップロードします。各ファイルのパスがKVのキー、ファイルの内容がKVの値として保存されます。
Workers Sitesテンプレートに基づいて作成されたWorkersスクリプトが、Cloudflareエッジネットワークにデプロイされます。
ユーザーからリクエストが来ると、WorkersがリクエストURLのパスに対応するキーをKVから検索し、ファイルの内容を読み込んでレスポンスとして返します。パスがファイルに一致しない場合は、適切なフォールバック（例: /index.html、カスタム404ページ）を処理します。

この仕組みにより、静的サイトはエッジネットワーク全体にキャッシュされ、非常に高速に配信されます。Workers Sitesは、CDN、キャッシュ、 Workersのカスタマイズ可能なリクエスト処理ロジック（認証、リダイレクトなど）のメリットを享受できます。

Wranglerでの設定 (`wrangler.toml`の `[site]`)

Workers Sitesを使用するには、wrangler.tomlに[site]セクションを追加し、静的ファイルが含まれるディレクトリを指定します。

“`toml
name = “my-static-site”

… その他の設定 …

[site]
bucket = “./dist” # 静的サイトのビルド済みファイルが入っているディレクトリ

オプション:

entry-point = “workers-site” # Workers Sites 用の Worker コードの場所 (デフォルト)

include = [“assets/*”] # 含めるファイルパターン (Glob形式)

exclude = [“build/*”] # 除外するファイルパターン (Glob形式)

“`

bucket: ビルド済みの静的サイトファイルが格納されているローカルディレクトリのパスを指定します。Wranglerはこのディレクトリの内容をKVにアップロードします。一般的なビルドツールでは、dist、build、publicなどのディレクトリがこれに相当します。
entry-point: Workers Sitesを実行するWorkersスクリプトの場所を指定します。デフォルトでは、Wranglerは.wrangler/tmp/pages-build-script_<hash>/worker.jsのようなパスにWorkers Sites用のスクリプトを自動生成して使用します。カスタムなWorkers Sitesスクリプトを使用したい場合は、そのパスを指定できますが、通常はデフォルトで十分です。
include / exclude: KVにアップロードするファイルをGlobパターンで絞り込むことができます。

Workers Sitesのビルドとデプロイ

wrangler.tomlに[site]セクションを設定したら、通常のwrangler deployコマンドを実行します。

bash wrangler deploy

wrangler deployは、[site]セクションが存在する場合、以下の追加処理を行います。

静的ファイルの入ったbucketディレクトリの内容を読み込みます。
必要に応じて、Workers Sitesを実行するWorkersスクリプト（通常は自動生成されるもの）をビルドします。
指定されたバケットの内容をCloudflare Workers KVにアップロードします。WranglerがSites用の新しいKV名前空間を自動で作成し、バインディングを設定します。
WorkersスクリプトとKVバインディングをCloudflareにデプロイします。

デプロイが完了すると、Workersスクリプトが指定されたルートで有効化され、KVにアップロードされた静的ファイルが配信されるようになります。

注意: wrangler pages deployコマンドは、Cloudflare Pagesサービス専用のデプロイコマンドです。Workers Sitesとは別のサービスであり、使用するコマンドも異なります。Workers SitesはWorkersとKVを使用する静的サイト配信であり、wrangler deployコマンドでデプロイします。Cloudflare Pagesは、Gitリポジトリと連携して静的サイトを自動的にビルド・デプロイするサービスであり、wrangler pages deployコマンドやGit連携でデプロイします。混同しないように注意してください。

ローカル開発

wrangler devコマンドは、Workers Sitesのローカルエミュレーションもサポートしています。

bash wrangler dev

[site]セクションが設定されている場合、wrangler devはローカルで静的ファイルを提供するサーバーを起動し、Workersスクリプトはそのローカルサーバーからファイルをフェッチして配信する形で動作します。これにより、KVへのアップロードなしに、ローカルで静的サイトとWorkersの連携をテストできます。

Workers Sitesは、React, Vue, SvelteなどのSPAフレームワークや、Hugo, Jekyll, Astroなどの静的サイトジェネレーターで構築されたサイトを、Cloudflareエッジネットワーク上で高速に配信するための強力なオプションです。Wranglerの[site]設定とdeployコマンドは、このプロセスを大幅に簡素化します。

テスト戦略とCI/CD連携

信頼性の高いアプリケーションを構築するためには、自動化されたテストが不可欠です。Cloudflare Workersアプリケーションも例外ではありません。また、開発プロセスの効率化には、継続的インテグレーション/継続的デプロイメント（CI/CD）パイプラインが重要です。Wranglerは、Workersアプリケーションのテスト実行とCI/CD環境への組み込みをサポートします。

Workersアプリケーションのテスト

Workersコードは標準的なJavaScript/TypeScriptコードとして記述されるため、Vitest, Jest, Mochaなどの一般的なJavaScriptテストフレームワークを使用してテストできます。しかし、Workers特有のAPI（fetchイベント、Workers Runtime API、リソースバインディングなど）をテストするには、特別な環境が必要です。

Miniflare（現在はworkerdとしてWranglerに統合）は、Workers Runtimeをローカルでエミュレートするため、テスト実行環境として最適です。Wranglerは、テストフレームワークと連携してMiniflare/workerd上でWorkersコードを実行する手段を提供します。

VitestとWrangler/Miniflareを使ったテストの例:

プロジェクトにテスト関連の依存関係を追加します。

bash npm install -D vitest @cloudflare/workers-types unplugin-scoped-polymorphism
* vitest: テストフレームワーク
* @cloudflare/workers-types: Workers Runtime APIの型定義（TypeScriptの場合）
* unplugin-scoped-polymorphism: VitestがWorkers Runtimeのポリフィルを扱えるようにするためのプラグイン
vitest.config.ts（または.js）ファイルを作成し、テスト環境を設定します。

“`typescript
// vitest.config.ts
import { defineConfig } from ‘vitest/config’;
import UnpluginScopedPolymorphism from ‘unplugin-scoped-polymorphism’;

export default defineConfig({
plugins: [
UnpluginScopedPolymorphism({
// Workers Runtime API へのアクセスを許可
allowedBindings: [‘MY_KV’, ‘MY_DURABLE_OBJECT’], // wrangler.toml の binding 名を指定
}),
],
test: {
environment: ‘miniflare’, // テスト環境として miniflare (workerd) を指定
environmentOptions: {
// miniflare / workerd の設定を記述
miniflare: {
# wranger.toml の設定を読み込む
wranglerConfigPath: ‘./wrangler.toml’,
# wrangler.toml で定義された binding をテストでも使用できるようにする
kvNamespaces: [“MY_KV”],
durableObjects: { MY_DURABLE_OBJECT: “MyDurableObject” },
# シークレットや環境変数をテスト環境に渡す
bindings: { MY_VAR: “test_value” },
kvBindings: { MY_KV: “your_test_kv_namespace_id” }, # ローカルエミュレーションか本番 KV かは設定次第
// … その他の miniflare/workerd 設定 …
},
},
},
});
“`
テストコードを記述します（例: src/index.test.ts）。

“`typescript
import { describe, it, expect, beforeAll } from ‘vitest’;
import worker from ‘./index’; // テスト対象の Workers コードをインポート

// Vitest + Miniflare 環境で利用可能な型定義
declare const getMiniflareBindings: () => Env; // Env は index.ts で定義した型

describe(‘Worker’, () => {
let env: Env;

beforeAll(() => {
// テスト環境のバインディングを取得
env = getMiniflareBindings();
});

it(‘should return “Hello World!”‘, async () => {
const request = new Request(“http://localhost/”);
const response = await worker.fetch(request, env, {} as ExecutionContext);
const json = await response.json();
expect(json).toEqual({
message: ‘Hello World!’,
requestUrl: ‘http://localhost/’,
method: ‘GET’,
});
});

// KV と連携するテストの例
it(‘should set and get from KV’, async () => {
const kv = env.MY_KV;
await kv.put(“test_key”, “test_value”);
const value = await kv.get(“test_key”);
expect(value).toBe(“test_value”);
});

// Durable Objects と連携するテストの例
it(‘should interact with Durable Object’, async () => {
const ns = env.MY_DURABLE_OBJECT;
const id = ns.idFromName(“test_object”);
const stub = ns.get(id);
```
let response = await stub.fetch("http://localhost/?action=increment");
expect(await response.text()).toBe("State incremented to 1");

response = await stub.fetch("http://localhost/?action=get");
expect(await response.text()).toBe("Current state: 1");
```
});
});
“`
package.jsonにテストスクリプトを追加します。

json "scripts": { "test": "vitest" }
コマンドラインでテストを実行します。

bash npm test

このように、Wranglerのローカル開発環境の基盤であるworkerd（Miniflare）は、テストフレームワークと組み合わせることで、Workersコード（エッジAPIやリソースバインディングを含む）の単体テストや結合テストを高速かつ忠実に実行できます。

CI/CDパイプラインへの組み込み

WranglerコマンドはCLIツールなので、GitHub Actions, GitLab CI, CircleCIなどのCI/CDプラットフォームに簡単に組み込むことができます。

一般的なCI/CDパイプラインのステップは以下のようになります。

Checkout: リポジトリからコードをチェックアウトします。
Node.jsセットアップ: Node.js環境をセットアップします。
依存関係のインストール: npm install（またはyarn install, pnpm install）を実行します。
ビルド: npm run buildのようなビルドコマンドを実行します。（Wranglerのデフォルトビルドを使用する場合は不要かもしれません）
テスト: npm testを実行して自動テストを実行します。テストが失敗した場合はパイプラインを停止します。
Cloudflare認証: CI環境でCloudflareアカウントに認証します。APIトークンを使用するのが一般的です。CF_API_TOKEN環境変数にAPIトークンを設定しておくと、Wranglerは自動的にそのトークンを使用します。
デプロイ: wrangler deployコマンドを使用してWorkersをデプロイします。ブランチ名やタグに基づいて、デプロイする環境（--env stagingなど）を切り替えることができます。

GitHub Actionsの例:

“`yaml
name: Deploy to Cloudflare Workers

on:
push:
branches:
– main # main ブランチへのプッシュで本番デプロイ
– staging # staging ブランチへのプッシュでステージングデプロイ
pull_request:
branches:
– main # PR 作成時にテスト実行

jobs:
build-and-test:
runs-on: ubuntu-latest
steps:
– uses: actions/checkout@v3
– uses: actions/setup-node@v3
with:
node-version: ’18’
– name: Install dependencies
run: npm install
– name: Build
run: npm run build # カスタムビルドを使用する場合
– name: Run tests
run: npm test

deploy-staging:
needs: build-and-test # ビルドとテストが成功した場合のみ実行
runs-on: ubuntu-latest
if: github.ref == ‘refs/heads/staging’ # staging ブランチの場合のみ実行
steps:
– uses: actions/checkout@v3
– uses: actions/setup-node@v3
with:
node-version: ’18’
– name: Install dependencies
run: npm install
– name: Publish Staging Worker
uses: cloudflare/wrangler-action@v3 # Wrangler を使用するアクション
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }} # シークレットとして設定
environment: ‘staging’ # wrangler.toml の環境名
# other options…

deploy-production:
needs: build-and-test # ビルドとテストが成功した場合のみ実行
runs-on: ubuntu-latest
if: github.ref == ‘refs/heads/main’ # main ブランチの場合のみ実行
steps:
– uses: actions/checkout@v3
– uses: actions/setup-node@v3
with:
node-version: ’18’
– name: Install dependencies
run: npm install
– name: Publish Production Worker
uses: cloudflare/wrangler-action@v3 # Wrangler を使用するアクション
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }} # シークレットとして設定
# environment は指定しない (デフォルト環境にデプロイ)
# other options…
“`

Cloudflare APIトークンは、GitHub ActionsのSecrets機能など、CI/CDプラットフォームの安全な方法で保存・管理してください。直接Workflowファイルに記述しないでください。

Wranglerは、Workersアプリケーションのテスト容易性とCI/CD環境への適応性を高めることで、モダンなソフトウェア開発プラクティスをWorkersにも適用できるようにします。

監視とログ (`wrangler tail`)

アプリケーションが本番環境で稼働し始めた後、その挙動を監視し、問題発生時にログを確認することは運用上不可欠です。Cloudflare Workersは、リクエストごとの詳細なログを提供しており、Wranglerのwrangler tailコマンドを使用することで、これらのログをリアルタイムで確認できます。

`wrangler tail` コマンドの使い方

デプロイ済みのWorkersのログを監視するには、プロジェクトのルートディレクトリ（wrangler.tomlがある場所）で以下のコマンドを実行します。

bash wrangler tail

このコマンドは、指定されたWorkers（wrangler.tomlのnameで指定されたWorker）に対するCloudflareエッジネットワーク上の実行ログを、発生と同時にターミナルにストリーム表示します。

ログには、リクエスト情報（URL、メソッド、ヘッダーなど）、Workersスクリプトの実行状況、およびconsole.logなどで出力されたメッセージが含まれます。エラー発生時には、スタックトレースなどの詳細な情報も表示されます。

“`

wrangler tail の出力例

LOG http://example.com/api/users GET
{
“request”: {
“method”: “GET”,
“url”: “http://example.com/api/users”,
…
},
“eventTimestamp”: 1678886400000,
“outcome”: “ok”, # 実行結果 (ok, exception, limitExceeded, etc.)
“scriptName”: “my-workers-app”,
“logs”: [ # console.log などで出力されたログ
{
“level”: “log”,
“message”: [“Fetching users from DB…”],
“timestamp”: 1678886400010
}
],
“exceptions”: [], # 例外が発生した場合
“durationMs”: 15, # 実行時間
“cpuTimeMs”: 5, # CPU 時間
“memory”: 10, # メモリ使用量 (MB)
…
}
“`

オプション (`wrangler tail --<option>`)

wrangler tailコマンドにはいくつかの便利なオプションがあります。

--url <URL>: 特定のURLパターンに一致するリクエストのログのみをフィルタリングします。
--method <メソッド>: 特定のHTTPメソッド（GET, POSTなど）のリクエストのログのみをフィルタリングします。
--status <ステータスコード>: 特定のHTTPステータスコード（200, 404, 500など）のレスポンスを返したリクエストのログのみをフィルタリングします。
--header <ヘッダー名>:<値>: 特定のヘッダーを含むリクエストのログのみをフィルタリングします。
--sampling-rate <レート>: ログのサンプリングレートを指定します（0.1 = 10%）。大量のリクエストがある場合に便利です。
--status-outcome <outcome>: 特定の実行結果（ok, exception, limitExceededなど）のログのみをフィルタリングします。
--format <形式>: 出力形式を指定します（jsonまたはpretty）。

例: 5xxエラーを返したリクエストのログのみを表示する

bash wrangler tail --status 5xx

例: 特定のURLへのPOSTリクエストのログのみを表示する

bash wrangler tail --url "*/api/users" --method POST

Environmentsとの連携

特定の環境にデプロイされたWorkersのログを監視したい場合は、--envオプションを使用します。

bash wrangler tail --env staging

これにより、wrangler.tomlの[environments.staging]で指定されたWorkersの名前のログがストリーム表示されます。

`console.log`などの出力

Workersコード内でconsole.log(), console.error(), console.warn() などを使用すると、その出力はwrangler tailで表示されるログに含まれます。デバッグのためにこれらのメソッドを積極的に利用できます。

``typescript export default { async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> { console.log(Received request for: ${request.url}`);

try {
  // ... 処理 ...
  console.log("Processing successful");
  return new Response("OK");
} catch (error: any) {
  console.error("An error occurred:", error);
  return new Response("Internal Server Error", { status: 500 });
}

},
};
“`

その他の監視機能

wrangler tailはリアルタイムログ監視に便利ですが、履歴ログの検索や集計、パフォーマンス分析などには、CloudflareダッシュボードのWorkers AnalyticsやLogs Explorer機能を利用するのが一般的です。これらのツールは、Wranglerとは直接連携しませんが、Workersの運用において重要な役割を果たします。

Wranglerのwrangler tailコマンドは、開発中や問題発生時の迅速なログ確認に非常に役立ちます。ローカル開発のwrangler devと組み合わせることで、開発・テスト・デバッグのサイクルをスムーズに行うことができます。

高度なトピックと実践的ヒント

ここまでにWranglerの基本的な機能と主要な側面を網羅してきましたが、さらにWorkers開発を効率化し、高度なユースケースに対応するためのWrangler関連のトピックや実践的なヒントをいくつか紹介します。

複数のWorkersプロジェクトを管理する

複雑なアプリケーションでは、複数のWorkersスクリプトを作成し、それぞれが特定の役割を担うマイクロサービスのような構成を取ることがあります。Wranglerでは、モノリポ（Monorepo）構造で複数のWorkersプロジェクトを管理することが可能です。

ルートディレクトリにpackage.jsonを作成します（npm init -yなど）。
各Workersプロジェクトをサブディレクトリに作成します（例: packages/api-worker, packages/auth-workerなど）。各サブディレクトリ内に独自のwrangler.tomlとソースコードを配置します。
ルートのpackage.jsonで、各サブディレクトリのWorkerを操作するためのスクリプトを定義します。例えば、LernaやTurborepoのようなモノレポ管理ツールを使用すると、依存関係の管理やスクリプトの実行が容易になります。あるいは、単に各ディレクトリでWranglerコマンドを実行するスクリプトを作成しても良いでしょう。

json // package.json (ルート) { "scripts": { "dev:api": "cd packages/api-worker && wrangler dev", "dev:auth": "cd packages/auth-worker && wrangler dev", "deploy:api:staging": "cd packages/api-worker && wrangler deploy --env staging", "deploy:auth:production": "cd packages/auth-worker && wrangler deploy --env production" }, "workspaces": [ "packages/*" # npm/yarn/pnpm の workspaces 機能を使用する場合 ] }
異なるWorkers間の連携には、前述のService Bindingsを使用します。wrangler.tomlで他のWorkersを名前で参照してバインドします。

パフォーマンス最適化の視点

Wrangler自体が直接パフォーマンス最適化を行うわけではありませんが、Workersのパフォーマンスに影響を与える開発プラクティスをサポートします。

ビルドサイズの最適化: esbuildのような高速で効率的なバンドラーを使用することで、Workersスクリプトのサイズを小さく保つことができます。小さいスクリプトは、Cold Startのオーバーヘッドを最小限に抑えるのに役立ちます。Wranglerのデフォルトビルドはesbuildを使用しているため、通常はこの点に優れています。
compatibility_dateとcompatibility_flagsの最新化: 最新のランタイム機能や最適化を利用するために、これらの設定を常に最新に保つようにしましょう。
外部依存関係の削減: WorkersはNode.jsの組み込みモジュールの一部（crypto, url, Bufferなど）をサポートしていますが、ファイルシステムI/Oなど、Node.js固有の機能はサポートされていません。また、npmパッケージを使用する場合、Workersランタイムでサポートされていないコードが含まれているとエラーになることがあります。Wranglerはデプロイ前に警告を表示することがありますが、事前に依存関係がWorkers互換であるか確認することが重要です。
wrangler devを使ったベンチマーク: wrangler devはWorkers Runtime (workerd) 上で実行されるため、ローカルでのパフォーマンス特性はエッジ環境に近い傾向があります。ただし、ネットワークレイテンシやエッジ固有の分散に関する部分はエミュレートされないため、最終的なパフォーマンス確認は本番環境で行う必要があります。

Wrangler設定のインポート/エクスポート

wrangler.tomlの設定はCloudflareのAPIにも反映されますが、Cloudflareダッシュボードで手動で行ったWorkersの設定をWranglerの設定ファイルとしてエクスポートしたり、その逆を行ったりする直接的なWranglerコマンドは（現時点では）提供されていません。

しかし、Cloudflare APIを使用してWorkersの設定を取得し、それをTOML形式に変換するスクリプトを自作することは可能です。また、wrangler.tomlは単なる設定ファイルなので、Gitなどのバージョン管理システムで管理し、CI/CDパイプラインで常にこのファイルに基づいた設定を適用することで、設定の一貫性を保つことができます。

Wranglerのバージョンアップ

Wranglerは活発に開発されており、新しい機能の追加や改善が頻繁に行われます。最新の機能や修正を利用するためには、定期的にWranglerをアップデートすることが推奨されます。

“`bash
npm update -g wrangler

または

yarn global upgrade wrangler

または

pnpm update -g wrangler
“`

新しいバージョンにアップデートする前に、リリースノートを確認し、破壊的変更がないか確認すると良いでしょう。

Wranglerのヘルプ機能

Wranglerコマンドの各機能やオプションについて詳しく知りたい場合は、-hまたは--helpオプションを使用します。

bash wrangler -h # 全体ヘルプ wrangler deploy -h # deploy コマンドのヘルプ wrangler kv -h # kv 関連コマンドのヘルプ

これにより、利用可能なコマンド、オプション、引数などが表示されます。

ローカル開発時のHTTPS

wrangler devはデフォルトでHTTPで起動しますが、HTTPSで開発したい場合は--local-protocol=httpsオプションを使用します。ただし、自己署名証明書に関する警告が表示される場合があります。

bash wrangler dev --local-protocol=https

Wranglerの進化と将来

Cloudflare Workersは急速に進化しており、それに伴いWranglerも継続的に改善・拡張されています。Wranglerの過去のバージョン（特にwrangler@1）から現在のバージョン（wrangler@3以降）への進化は目覚ましく、特にローカル開発環境の忠実度向上（Miniflareからworkerdへ）と、多様なエッジリソース（DO, R2, D1, Queues, AIなど）への対応強化が進んでいます。

workerdのオープンソース化は、WranglerとWorkersエコシステムにとって大きな一歩です。ローカル開発と本番実行環境の差異が最小化されたことで、開発者の信頼性が向上し、Workersランタイム自体の開発にもコミュニティが貢献できるようになりました。

今後も、Cloudflareが新しいエッジサービスやWorkers機能を提供するにつれて、Wranglerはそれらをサポートするための機能を追加していくと考えられます。例えば、Workers Catalog（Workersのテンプレートやコンポーネントの共有）、さらなるローカル開発機能の強化、CI/CD連携の簡素化などが期待されます。

Cloudflare Workers開発コミュニティも非常に活発であり、Wranglerはコミュニティからのフィードバックを取り入れながら進化しています。もしWranglerを使用していて問題に遭遇したり、新しい機能の提案があれば、GitHubのリポジトリ（https://github.com/cloudflare/workers-sdk）でIssueを報告したり、コントリビュートしたりすることができます。

Wranglerは、単なるCLIツールではなく、Cloudflare Workersプラットフォーム全体の開発体験を定義する重要な要素です。その継続的な進化は、エッジコンピューティングにおけるサーバーレス開発をさらに accessible かつ強力なものにしていくでしょう。

まとめ：WranglerでWorkers開発を加速する

Cloudflare Workersは、エッジコンピューティングの力を開発者に提供し、低レイテンシでスケーラブルなアプリケーション構築を可能にする革新的なプラットフォームです。そして、Wranglerは、このWorkersプラットフォーム上での開発、テスト、デプロイ、管理を劇的に効率化するための不可欠なツールです。

この記事では、Wranglerの概要から始まり、そのインストール、プロジェクト作成、心臓部であるwrangler.tomlファイルの詳細な設定、workerdを基盤とした強力なローカル開発環境、KV、Durable Objects、R2、Service Bindings、D1といった多様なエッジリソースとの連携、シークレット管理、ビルドプロセス、Environmentsとルーティングを活用したデプロイ戦略、Workers Sitesでの静的サイト配信、テストとCI/CDパイプラインへの組み込み、リアルタイムログ監視のためのwrangler tail、さらには高度なトピックや実践的なヒント、そしてWranglerの進化について、約5000語にわたり徹底的に解説しました。

Wranglerを使いこなすことで、開発者は以下のメリットを享受できます。

開発効率の向上: wrangler initによる迅速なプロジェクト作成、wrangler devによる高速なローカル開発とホットリロードにより、コードのイテレーション速度が向上します。
信頼性の高いテスト: workerdベースのローカル開発環境と、テストフレームワークとの連携により、本番環境に近い状態でコードをテストできます。
簡単なデプロイ: wrangler deployコマンド一つで、ビルド、アップロード、設定更新、ルーティング設定まで自動的に行われます。Environments機能により、環境ごとの設定管理も容易です。
リソース連携の簡素化: wrangler.tomlで各種エッジリソース（KV, DO, R2, D1など）とのバインディングを簡単に設定し、ローカルでエミュレーションできます。
安全なシークレット管理: wrangler secretコマンドにより、機密情報を安全に管理し、Workersにバインディングできます。
CI/CDへの統合: CLIツールとして設計されているため、既存のCI/CDパイプラインに簡単に組み込むことができます。

Wranglerは、Cloudflare Workers開発におけるベストプラクティスを体現しており、Workersの強力な機能を最大限に引き出すための橋渡し役を果たしています。Workers開発をこれから始める方も、すでに Workersを利用している方も、Wranglerの機能を深く理解し、活用することで、より生産的かつ効率的にエッジアプリケーションを構築できるようになるでしょう。

この記事が、あなたのCloudflare Workers開発の旅において、信頼できるパートナーとしてのWranglerを理解し、使いこなすための一助となれば幸いです。エッジコンピューティングの未来を、Wranglerと共に切り開いていきましょう。

Wranglerとは？ Cloudflare Workers開発ツール徹底解説

はじめに：エッジコンピューティングとCloudflare Workersの台頭

Cloudflare Workersとは？ その仕組みと特徴

Workersの仕組み：V8 Isolates

Workersの主な特徴

従来のサーバーレス（例: AWS Lambda）との比較

Wranglerとは？ その役割と重要性

なぜWranglerが必要なのか？

Wranglerの主な役割

Wranglerのインストールと認証

Node.jsのインストール

Wranglerのインストール

Yarnの場合

pnpmの場合

または

Cloudflareアカウントとの認証 (wrangler login)

Workersプロジェクトの作成 (wrangler init)

wrangler init コマンドの使い方

プロジェクト作成と依存関係のインストールが実行される

プロジェクト構造

Wrangler.toml: 設定ファイルの徹底解説

wrangler.toml の基本的な構造と主要な設定項目

Workerの名前。CloudflareダッシュボードやCLIで表示される名前。

Workersスクリプトのビルド後のファイルパスを指定。

通常は src ディレクトリにあるコードがビルドされて生成される。

デフォルトのビルド設定を使用する場合、この項目は不要。

script = “dist/worker.js”

Workersスクリプトのメインエントリポイントを指定。

src/index.ts (または .js) を使用する場合、ほとんどの場合この項目は不要。

main = “src/index.ts” # または “src/index.js”

ランタイムAPIの互換性日を指定。特定の機能を有効にするための日付。

最新の日付を指定するのが一般的。

ランタイムAPIの互換性フラグを指定。特定の実験的機能などを有効にする。

compatibility_flags = [ “streams_enable_readable_stream_async_iterator” ]

ビルド設定。カスタムビルドプロセスを指定する場合に使用。

[build]

# コマンドでビルドする場合

command = “npm run build”

# ビルド後の出力ディレクトリ

watch = [“src”] # 変更を監視するディレクトリ（ローカル開発時）

# ビルドスクリプトのタイプ (esbuild, webpack, etc.)

# packer = “esbuild”

# # esbuild オプション

# [build.upload]

# format = “modules” # または “service-worker”

# main = “src/index.ts” # ビルド対象のエントリポイント

環境変数。Workersから process.env や env オブジェクト経由でアクセスできる。

wranger secrets コマンドで設定するシークレットとは異なる。

vars = { MY_VAR = “my_value”, ANOTHER_VAR = “another_value” }

リソースバインディング。KV, DO, R2, Service Binding など、Workersが連携する外部リソースの設定。

KV Namespaces とのバインディング

[[kv_namespaces]]

binding = “MY_KV” # コード内で env.MY_KV としてアクセス

id = “YOUR_KV_NAMESPACE_ID” # Cloudflareダッシュボードまたは wrangler kv:namespace create で取得

Durable Objects とのバインディング

[[durable_objects.bindings]]

name = “MY_DO” # コード内で env.MY_DO としてアクセス

class_name = “MyDurableObject” # DOクラスの名前（コード内で定義）

# script_name = “my-other-worker” # 別Workerで定義されたDOクラスを参照する場合

R2 Buckets とのバインディング

[[r2_buckets]]

binding = “MY_R2_BUCKET” # コード内で env.MY_R2_BUCKET としてアクセス

bucket_name = “my-r2-bucket-name” # R2バケット名

Service Bindings (他の Workers へのバインディング)

[[services]]

binding = “MY_SERVICE” # コード内で env.MY_SERVICE としてアクセス

service = “other-worker-name” # 連携する他のWorkerの名前

# environment = “production” # 連携するWorkerの環境（省略時はデフォルト）

D1 Database とのバインディング

[[d1_databases]]

binding = “DB” # コード内で env.DB としてアクセス

database_name = “my-database” # D1データベース名

database_id = “YOUR_D1_DATABASE_ID” # Cloudflareダッシュボードまたは wrangler d1 create で取得

Workers AI とのバインディング

[[ai.ai_bindings]]

name = “AI” # コード内で env.AI としてアクセス

Queues とのバインディング

[[queues.producers]]

binding = “MY_QUEUE_PRODUCER” # コード内で env.MY_QUEUE_PRODUCER としてアクセス

queue = “my-queue-name” # キュー名

Cloudflare Workersとは？その仕組みと特徴

Wranglerとは？その役割と重要性

Cloudflareアカウントとの認証 (`wrangler login`)

Workersプロジェクトの作成 (`wrangler init`)

`wrangler init` コマンドの使い方

ローカル開発環境 (`wrangler dev`): Miniflareからworkerdへ

`wrangler dev` コマンドの使い方

`workerd` (Cloudflare Workers Runtime)

オプション (`wrangler dev --<option>`)