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."
fi

package.jsonに"clean:wrangler": "bash scripts/clean-wrangler-cache.sh"を登録し、問題発生時にチームメンバーが即座に実行できるようにする。

学び