Gadget 45：run-local を解剖する

pnpm run-local が実際に何をしているのか。内部構造を分解して挙動を操る

run-local を解剖する

pnpm run-local の「中身」を分解して、何が起きているかを完全に把握します。

目的

  • 起動の仕組みを理解し、応用（ポート変更・バインディング変更・デバッグ）ができる
  • 「なぜそう動くのか」を 1 から説明できる

前提条件

  • 起動できる環境（00）
  • 読める力: Node.js / shell の雰囲気がわかる人向け

実体

pnpm run-local は node scripts/run-local.mjs を実行しています。

内部でやっていること（5 段階）

  1. 開発用ワーカー構成を自動生成
    • wrangler.dev.jsonc（gitignored）をルート・各 gatekeeper・workshop-backend に書き出す
  2. Gatekeeper を全数サービスバインディング
    • packages/ 下の gatekeeper-* を読み取り、それぞれを service として backend に接続
    • 例: GATEKEEPER_GITHUB
  3. backend に ADMINS=["admin"] を挿入
    • ローカルで admin 機能を試すための用意
  4. フロント資産の配信設定
    • --serve-frontend-assets により workshop-frontend/dist を backend が配信
  5. wrangler dev をマルチコンフィグで同時起動
    • ルート Router・backend・各 Gatekeeper の wrangler.dev.jsonc を -c で複数指定し、 単一ランタイム（workerd）でまとめて起動

つまり

「Web サーバー 1 本」ではなく、 開発用 Router + バックエンド + 各 Gatekeeper が 1 つの workerd ランタイムで同時に動く 構成です。

観察する

# 生成物と起動プロセスを見る
ls packages/workshop-backend/wrangler.dev.jsonc
ps aux | grep -E "wrangler|workerd" | grep -v grep

裏技（応用）

やりたいこと 方法
特定 Gatekeeper を外して起動 packages/gatekeeper-* を一時退避→再起動
ポートを変える VITE_BACKEND_HOST と --port を連動
生成 config を確認 起動後に wrangler.dev.jsonc を cat
AI を使う --use-workers-ai-binding（→ 要 wrangler login）

よくある失敗

症状 原因 対処
手動で wrangler dev する人と挙動が違う run-local が自動生成した config を読んでいない wrangler.dev.jsonc を確認
Gatekeeper が増えたのに bind されない 起動時点で未認識 再起動（自動探索）
ポートを変えたのに UI が開かない フロントの想定ホストとズレ VITE_BACKEND_HOST を同時指定

確認

次に読む