この記事はひとりCloudflareを使い倒す Advent Calendar 2025 の2日目です

どうも、とれいすあっぷと申します。
「ひとりCloudflareを使い倒す Advent Calendar 2025」2日目です。

Cloudflare を使い倒すにあたって必要なことってなんでしょうか。

マジカルバナナ♪

「Cloudflare」といったら「Cloudflare Workers」♪

「Cloudflare Workers」といったら「Wrangler」♪

半分くらい冗談ですが、Wrangler が使えると Workers がもっと便利になると思います。
ということで、詳しいことを理解して行きましょう。

この記事では

Wrangler って何？何ができるの？
Wrangler の使い方
Wrangler の内部実装をちょっとだけ

を解説してみようかなと思います。

Wrangler って何?

Wrangler, the Cloudflare Developer Platform command-line interface (CLI), allows you to manage Worker projects.

Wrangler は、Cloudflare Developer Platform の CLI で、Worker Project の管理ができます。(筆者訳)

気付いた方もいらっしゃるかもしれませんが、Wrangler は Cloudflare Workers の中にいる CLI ツールです。

Wrangler は Workers まわりのことが比較的何でもできます。

Workers プロジェクトだけで言えば、

init: create-cloudflare-cli tool を使って、Worker Project を作る
dev: Workers をローカルで実行する
deploy: ローカルのコードを Cloudflare にデプロイする
deployments: Cloudflare Workers でデプロイされているやつの状況を見る
rollback: 今 Cloudflare Workers で動いているコードをロールバックする
types: 型定義を自動で生成する
secret: シークレットを管理する
delete: Cloudflare Workers で動いているコードを消し飛ばす

ってことができます。(一例です)

また、Workers プロジェクト以外にも、

containers: Cloudflare Container (コンテナ)
d1: Cloudflare D1 (データベース)
hyperdrive: Cloudflare Hyperdrive (手元の DB を世界に乗っける)
vectorize: Cloudflare Vectorize (AI とかに使う Vector Database)
kv: Cloudflare Workers KV (Key-Value ストア)
r2: Cloudflare R2 (オブジェクトストレージ)
workflows: Cloudflare Workflows (一連の流れやってくれるやつ)
pages: Cloudflare Pages (Reactとかが乗っけてホスティングできるやつ、今は Workers 推奨)
pipelines: Cloudflare Pipelines (ログとかのストリームデータをまとめてくれるやつ、BigQuery 的な？※要調査)
queues: Cloudflare Queues (バッチ処理とかできるようにしてくれるやつ)

といった Cloudflare 製品について、Wrangler から触れます。やったぁ！

とにかく、Cloudflare 製品をローカルから触りたいなら、とりあえず入れとけ！って感じです。
(Cloudflare Developer Platform CLI と公式に書いてある)

Wrangler の使い方

Wrangler はとりあえずローカルに落とさないことには始まりません。

その前に「Node.js と npm が入っていることを確認してください」と書いてあります。

To install Wrangler, ensure you have Node.js and npm installed,

で、Node.js はできれば Volta とか nvm を使って入れてほしいな、と書いてあります。

preferably using a Node version manager like Volta or nvm.

これは理由もちゃんと書いてあります。

Using a version manager helps avoid permission issues and allows you to change Node.js versions.

Version Manager を使うと、権限問題の回避や、そもそも Node.js のバージョンを自分で簡単に変えられる、という利点があるためです。

Version Manager を使ったことないなぁという方は、今のうちに入れておきましょう。
私は NVM for Windows を使っています。

さて、そしたら npx wrangler を実行してみましょう。
(これは実行したディレクトリには追加されず、npm のキャッシュフォルダに入ります。参考ページ )

Need to install the following packages:
wrangler@4.47.0
Ok to proceed? (y)

パッケージを入れるか聞いてきます。
y でそのまま入れます。

COMMANDS
  wrangler docs [search..]        📚 Open Wrangler's command documentation in your browser

  wrangler init [name]            📥 Initialize a basic Worker
  wrangler dev [script]           👂 Start a local server for developing your Worker
  wrangler deploy [script]        🆙 Deploy a Worker to Cloudflare
  wrangler setup                  🪄 Setup a project  to work on Cloudflare [experimental]
  wrangler deployments            🚢 List and view the current and past deployments for your Worker       
  wrangler rollback [version-id]  🔙 Rollback a deployment for a Worker
  wrangler versions               🫧 List, view, uplooad and deploy Versions of your Worker to Cloudflare  
  wrangler triggers               🎯 Updates the triggers of your current deployment [experimental]       
  wrangler delete [script]        🗑  Delete a Worker from Cloudflare
  wrangler tail [worker]          🦚 Start a log tailing session for a Worker
  wrangler secret                 🤫 Generate a secret that can be referenced in a Worker
  wrangler types [path]           📝 Generate types from your Worker configuration

  wrangler kv                     🗂️  Manage Workers  KV Namespaces
  wrangler queues                 📬 Manage Workers Queues
  wrangler r2                     📦 Manage R2 buckets & objects
  wrangler d1                     🗄  Manage Workers D1 databases
  wrangler vectorize              🧮 Manage Vectorize indexes
  wrangler hyperdrive             🚀 Manage Hyperdrive databases
  wrangler cert                   🪪 Manage client mTTLS certificates and CA certificate chains used for secured connections [open-beta]
  wrangler pages                  ⚡️ Configure Clouddflare Pages
  wrangler mtls-certificate       🪪 Manage certificaates used for mTLS connections
  wrangler containers             📦 Manage Containers [open-beta]
  wrangler pubsub                 📮 Manage Pub/Sub brokers [private beta]
  wrangler dispatch-namespace     🏗️  Manage dispatchh namespaces
  wrangler ai                     🤖 Manage AI models
  wrangler secrets-store          🔐 Manage the Secrets Store [open-beta]
  wrangler workflows              🔁 Manage Workflows
  wrangler pipelines              🚰 Manage Cloudflare Pipelines [open-beta]
  wrangler vpc                    🌐 Manage VPC [open-beta]
  wrangler login                  🔓 Login to Cloudflare
  wrangler logout                 🚪 Logout from Cloudflare
  wrangler whoami                 🕵️  Retrieve your uuser information

GLOBAL FLAGS
  -c, --config    Path to Wrangler configuration file  [string]
      --cwd       Run as if Wrangler was started in the specified directory instead of the current working directory  [string]
  -e, --env       Environment to use for operations, and for selecting .env and .dev.vars files  [string] 
      --env-file  Path to an .env file to load - can be specified multiple times - values from earlier files are overridden by values in later files  [array]  
  -h, --help      Show help  [boolean]
  -v, --version   Show version number  [boolean]     

Please report any issues to https://github.com/cloudflare/workers-sdk/issues/new/choose

Wrangler がローカルに落ちてきました。これで、いつでも npx wrangler で Wrangler をつつけます。

…とはいえ、これは Cloudflare が公式に推奨しているものではありません。

Wrangler はプロジェクトごとに使っているバージョンが異なることも多く、故にちゃんとバージョンを package.json に書いて置くことで、おま環を防ぐ意味合いがあるのです。(これはどのライブラリでも等しくそう)

ということで、良い子の皆さんはちゃんと npm i -D wrangler でバージョンを固定して使うようにしましょう。

Wrangler の内部実装をちょっとだけ読む

果たして私に読めるコードはあるんでしょうか。

今回は、ログインしているユーザーが何なのかを調べる wrangler whoami コマンドについて、理解していきたいと思います。\

実行結果はこんな感じです。

 ⛅️ wrangler 4.49.1
───────────────────
Getting User settings...
👋 You are logged in with an OAuth Token, associated with the email test@example.com.
┌───────────────────────────────┬──────────────────────────────────┐
│ Account Name                  │ Account ID                       │
├───────────────────────────────┼──────────────────────────────────┤
│ test@example.com's Account    │ 11111111111111111111111111111111 │
└───────────────────────────────┴──────────────────────────────────┘
🔓 Token Permissions:
(許可されている権限たち)

シンプルに誰がログインしていて、権限がどんなもんだよ、って表示して教えてくれるやつです。

▼ 読んでいく Wrangler の GitHub Repository

とりあえず package.json を読みます。

こんな記述があります。
wrangler2 でも動く…ってコト？！

はい。動きます。
ローカルに Wrangler を入れて、npx wrangler2 ってやったら動きます。

wrangler2…？

歴史的には Wrangler legacy とのエイリアス確保のためみたいです。
が、Wrangler legacy は 1.5 年前に Deprecated になったので、消してもいいような…→ Discussion 開いてみた

https://github.com/cloudflare/workers-sdk/pull/40

wrangler ってやると ./bin/wrangler.js が実行されます。

特にここに注目です。

../wrangler-dist/cli.js はビルドの生成物です。
spawn で node を呼んで、cli.js を実行します。

まあとりあえず cli.js は置いといて、ソースコードを読んでみましょう。

whoami コマンドが registry.define で定義されていそうな雰囲気を感じます。

ということで、これが本当なのか探るべく registry.define を追っていきます。

まず、define は複数のコマンドやエイリアスが一気に定義できることがわかります。
それが for 文で 1 つずつ #defineOne(def) を通って、エイリアスやコマンド、名前空間を定義している、とかで処理が分かれていっています。

実際に登録していそうな #upsertDefinition について追っていきましょう。

CommandRegistry のコンストラクタで #DefinitionTreeRoot を作っているので、そいつを呼び出してコマンドツリーを作っています。

コメントに書いてある example を見て、理解してみましょう。

追加したコマンドや namespace によって、subtree が成長するんだなあ、ってことがわかります。
これ以上追っても得られるものがなさそうなので、引き返します。

さて、戻って戻って definition ですが、これは src/user/commands.ts を見るとわかります。

whoamiCommand が createCommand で定義されていて、その中で handler が実装されていますね。
この中にある await whoami(config, args.account) こそ、whoami の実装本体です。

追っていきましょう。

処理の順番としては

await getUserInfo(complianceConfig) でユーザーの情報を取る
printUserEmail(user) で今どういう認証方式でなんのアカウントにログインしているのか表示する
ComplianceRegion() で Region を表示する (政府レベルの認可とかそういう話らしい)
printAccountList(user) でアカウントの情報をテーブル方式で表示する
printTokenPermissions(user) でなんの権限があるか表示する

って感じですね。
単純だけどたくさんの処理を踏んでいることがわかります。

ということで、実装追えました！わかりやすいコードベースで助かりました。

内部処理追っていくと、実際のコマンドパースは Yargs を使っているみたいです。詳しく追う体力がなかったので書けていませんが、ぜひ見てみたいですね…。

最近見たコマンドラインパーサーだと gunshi とかもあるみたいなので、そのうち比較してみよっと。

おわりに

この記事では Wrangler をざっくり解説して、内部実装も追ってみました。

初めてこういうツールの内部実装を追ってみた感想ですが、読めるもんだなぁ…っていうのと、
あとは TODO コメントも結構見かけますね。こういうとこからコントリビューションにつなげていくんだなあと思います。

とにかく、Cloudflare Workers を遊ぶなら、Wrangler を入れておきましょう。