Wrangler v3 から v4 へ移行する

Wrangler v4 は、基盤システムと依存関係の更新に加え、Wrangler コマンドの一貫性と分かりやすさを高める改善に重点を置いたメジャーリリースです。これまでの Wrangler のメジャーバージョンは 基盤の書き換え ↗ や 再設計 ↗ でした。Wrangler のバージョン 4 の変更は、それよりかなり小さいです。いま Wrangler を使っているなら、作業の流れが大きく変わることはほとんどありません。

多くのユーザーは実質的な変更のないアップグレードになります。次の各節では、より重要な変更と、必要な場合の移行手順を説明します。

Worker プロジェクト内で最新の Wrangler v4 へアップグレードするには、次を実行します。

npm i -D wrangler@4

yarn add -D wrangler@4

pnpm add -D wrangler@4

bun add -d wrangler@4

アップグレード後、インストールを確認できます。

npx wrangler --version

yarn wrangler --version

pnpm wrangler --version

• 更新された Node.js サポートポリシー: 2022 年にサポート終了（End-of-Life）となった Node.js v16 は、Wrangler v4 ではサポートされません。Wrangler は Node.js の 公式サポートライフサイクル ↗ に従います。

• esbuild のバージョンアップ: Wrangler はデプロイ前に esbuild ↗ で Worker コードをバンドルしており、以前は esbuild v0.17.19 に固定されていました。Wrangler v4 は esbuild v0.24 を使い、動的なワイルドカードインポートに影響する場合があります。今後、Wrangler に同梱する esbuild のバージョンは定期的に更新します。esbuild は 1.0.0 未満のツールなので、バンドルの挙動に破壊的変更が含まれることがあります。とくに、Wrangler のマイナーバージョンで esbuild のバージョンを上げることがあります。

• コマンドの既定がローカルモード: ローカルとリモートのどちらでも実行できるコマンドは、すべてローカルが既定になります。API へ問い合わせるには --remote フラグが必要です。

• 非推奨のコマンドと設定を削除: レガシーなコマンド、フラグ、設定は削除されます。

Wrangler がサポートする Node.js のバージョンは、Node.js の公式ライフサイクル ↗ に合わせたものだけです。

• サポート対象: Current、Active LTS、Maintenance LTS
• サポート終了: Node.js v16（2022 年に EOL）

Wrangler のテストは v16 では実行されません。このバージョンを使い続けているユーザーは、未サポートの挙動に遭遇することがあります。サポートと Wrangler との互換性を続けるには、Node.js v16 を使っているユーザーは、サポート対象のバージョンへアップグレードする必要があります。

node --version

Wrangler v4 では esbuild を v0.17.19 から v0.24 へ上げます。改善（RPC で using キーワードを使えるなど）と、バンドル挙動の変更があります。

• 動的インポート: ワイルドカードインポート（例: import('./data/' + kind + '.json')）は、一致するファイルをすべて自動でバンドルに含めます。

ワイルドカードの動的インポートに依存しているユーザーは、不要なファイルがバンドルされることがあります。esbuild v0.19 より前は、動的パス付きの import 文（import('./data/' + kind + '.json') など）は、グロブパターン（*.json）に一致するファイルをすべてバンドルしませんでした。明示的に参照したファイル、または find_additional_modules で含めたファイルだけがバンドルされました。esbuild v0.19 以降、ワイルドカードインポートはグロブパターンに一致するファイルをすべて自動でバンドルします。不要なファイルがバンドルされることがあるので、ワイルドカードの動的インポートは避け、明示的なインポートを使う方がよい場合があります。

すべてのコマンドは 既定でローカルモード で実行されます。Wrangler には KV や R2 などのリソースへアクセスするコマンドが多くありますが、以前はローカルとリモートのどちらで動くかがコマンドごとに揃っていませんでした。たとえば D1 はローカルのデータストアへの問い合わせが既定で、API へ問い合わせるには --remote フラグが必要でした。一方 KV は、以前は API への問い合わせが既定（暗黙の --remote フラグ）で、ローカルのデータストアへ問い合わせるには --local フラグが必要でした。Wrangler 全体で挙動を揃えるため、各コマンドはいま --local フラグを既定で使い、API へ問い合わせるには明示的な --remote フラグが必要です。

例:

• 以前の挙動（Wrangler v3）: wrangler kv key get は既定でリモートへ問い合わせました。
• 新しい挙動（Wrangler v4）: wrangler kv key get は --remote を指定しない限り、ローカルへ問い合わせます。

データストアの参照や書き込みに wrangler kv key や wrangler r2 object コマンドを使っている場合は、以前と同じ挙動にするには --remote フラグを追加する必要があります。

grep -rE "wrangler (kv|r2)" --include="*.sh" --include="*.yml" --include="*.yaml" --include="Makefile" --include="package.json" .

# Before (Wrangler v3 - queried remote by default)
wrangler kv key get --binding MY_KV "my-key"

# After (Wrangler v4 - must specify --remote)
wrangler kv key get --binding MY_KV "my-key" --remote

Wrangler v2 と Wrangler v3 で以前非推奨になった機能は、すべて削除されます。加えて、Wrangler v3 のリリース期間中に非推奨になった次の機能も削除されます。

• Legacy Assets（wrangler dev/deploy --legacy-assets または設定ファイルの legacy_assets プロパティ）。代わりに Workers Static Assets へ移行 することを推奨します。
• レガシーな Node.js 互換性（wrangler dev/deploy --node-compat または設定ファイルの node_compat プロパティ）。代わりに nodejs_compat 互換性フラグ を使います。これには、レガシーな node_compat ポリフィルの機能と、ネイティブ実装の Node.js API が含まれます。
• wrangler version。代わりに wrangler --version で、現在の Wrangler のバージョンを確認します。
• getBindingsProxy()（import { getBindingsProxy } from "wrangler"）。代わりに getPlatformProxy() API を使います。引数はまったく同じです。
• usage_model。Workers Standard Pricing のロールアウト ↗ 以降、効果はありません。

# For TOML files
grep -E "(legacy_assets|node_compat|usage_model)\s*=" wrangler.toml

# For JSON files
grep -E "\"(legacy_assets|node_compat|usage_model)\"" wrangler.json wrangler.jsonc

grep -rE "wrangler.*(--legacy-assets|--node-compat)" --include="*.sh" --include="*.yml" --include="*.yaml" --include="Makefile" --include="package.json" .

grep -rE "getBindingsProxy" --include="*.js" --include="*.ts" --include="*.mjs" .