React Router v7 移行後、wrangler pages dev で起きる2つの環境問題
著者: ClaudeMix Team |
React Router v7への移行はコードの置換だけでは終わらない。wrangler pages dev環境で対処が必要な作業が2点あり、移行計画に最初から組み込まなければ「完了」報告後に予期せぬ追加作業として現れる。
症状
- 発生環境: React Router v7.13.1(移行前: Remix v2) / Cloudflare Pages・Workers /
wrangler pages dev/ Windows 11 vite devでは発生しない、wrangler pages dev固有の問題
原因と解決策
1. `[ignored-bare-import]` 警告
▲ [WARNING] [ignored-bare-import] Ignoring require() of module "node:events" ...Cloudflare WorkersのSSRビルド時、Node.jsビルトインモジュールのbare importがSSRバンドルに混入する。vite devはNode.jsネイティブ環境で動くため警告が出ないが、wrangler pages devは検出して警告を出す。
// vite.config.ts に追加するカスタムプラグイン
function removeNodeBareImports(): Plugin {
return {
name: "remove-node-bare-imports",
apply: "build",
generateBundle(_options, bundle) {
for (const [, chunk] of Object.entries(bundle)) {
if (chunk.type !== "chunk" || !chunk.isEntry) continue;
chunk.code = chunk.code.replace(/require\(["']node:[^"']+["']\);?\n?/g, "");
}
},
};
}動作に影響はないが、大量に出力されると本当に必要な警告を見落とすリスクがある。react-routerやwranglerのバージョンが上がると警告の粒度が変わることがあるため、次回の移行時にも再確認が必要。
2. Windows × wrangler キャッシュロック問題
ビルド成果物を更新してもブラウザに古い画面が表示され続け、サーバーを再起動しても変わらない。.wrangler/state/v3内のSQLiteファイルがNode.jsプロセスにロックされ、Windowsのファイルシステムではプロセス終了後もロックが残ることが原因(Mac/Linuxでは発生しない)。
#!/bin/bash
# scripts/clean-wrangler-cache.sh
WRANGLER_STATE=".wrangler/state/v3"
if [ -d "$WRANGLER_STATE" ]; then
rm -rf "$WRANGLER_STATE"
echo "Done. Restart 'wrangler pages dev' to apply changes."
fipackage.jsonに"clean:wrangler": "bash scripts/clean-wrangler-cache.sh"を登録し、問題発生時にチームメンバーが即座に実行できるようにする。
学び
wrangler pages devとvite devは同じコードでも異なるランタイムで動くため、両方での動作確認を移行の完了条件に含める- Windows固有の問題はMac/Linux開発者には再現しないため、チームに明示的に周知する必要がある
- typecheck側の問題はReact Router v7移行でtypecheckが壊れる4つの原因に記録した
- wranglerのキャッシュ問題は、
.wranglerディレクトリを「決定論的に再現すべき状態」として扱うという点で、db-resetスクリプトで.wranglerを物理削除しスキーマから再生成する設計という課題と根が同じ