React Router v7 移行後、wrangler pages dev で起きる2つの環境問題

はじめに

React Router v7 への移行をAIが完了させた翌朝、wrangler pages dev でbare-import警告が出始め、Windowsではキャッシュロックで古い画面が表示され続けました。この2点を移行計画に最初から組み込むための、Vite プラグインとクリーンアップスクリプトを記録します。

React Router v7 移行でこんなことありませんか？

React Router v7 への移行をAIに依頼した。コードの置換は完璧だった。ビルドも通った。「完了」と思って報告した。
翌朝、wrangler pages dev を起動すると見慣れない警告が並ぶ。Windowsでは、変更したはずの画面が古いまま表示され続ける。これらは「コードのバグ」ではない。しかし計画には入っていなかった。
予期せぬ作業が増えた。報告が増えた。完了したはずの移行が、まだ終わっていない。

この記事をお勧めしない人

wrangler pages dev を使わず、vite dev だけで開発している人
Windowsではなく Mac や Linux で開発している人（キャッシュロック問題は発生しない）
React Router v7 への移行を当面予定していない人

もし一つでも当てはまらないなら、読み進める価値があるかもしれません。

計画に入っていない作業が計画を腐らせる

「コードは正しいはずなのに wrangler が想定通りに動かない」という状況が生まれ、原因の特定に時間が取られる
「完了」と報告した後に追加作業が発生し、チームへの説明コストが上がる
問題が起きてから調べ始めると、公式ドキュメントに記載がないため自力で解決するしかない状況に陥る

計画に組み込むための情報という使い方

この記事を読めば、wrangler 作業2点が最初から移行スコープに入った状態で計画を立てられる
具体的には、対処用の Vite プラグインとクリーンアップスクリプトが実装済みで、コードベースに先に用意できる設計図を手に入れられる
この記事の内容は、このブログ自身（React Router × Cloudflare Edge、Windows 開発環境）で本番検証済みの一次情報であり、公式ドキュメントには記載のない実践知です

このブログもそうでした

このブログの React Router v7 移行作業で、まさにこの2点が計画外の作業として現れました。問題が発生すること自体は想定内でも、計画に入っていなければ「予期せぬ作業」になります。
この記事で、2点の問題と対処コードをそのまま持ち帰れるように書きました。

📝 概要

問題が発生すること自体は問題ではない。【予期せず計画外に現れることが問題だ。】

React Router v7 移行には、コードの置換とは別に、wrangler 開発環境で対処が必要になる作業が2点あります。どちらも「移行後に発覚する」のではなく、「移行計画に最初から含めておく」ことで、予期せぬ作業をなくせます。

本記事では、この2点の内容・発生条件・対処コードを記録します。問題を防ぐためではなく、【計画に組み込むための情報】として使えます。

発生環境

【フレームワーク】: React Router v7.13.1（移行前: Remix v2）
【ホスティング】: Cloudflare Pages / Workers
【ビルドツール】: Vite
【ローカル開発】: wrangler pages dev
【その他】: Windows 11（キャッシュロック問題は Windows 固有）

wrangler 作業2点と対処コード

⚠️ 作業1: `[ignored-bare-import]` 警告への対処

【症状】

wrangler pages dev を起動すると、以下のような警告が大量に出力されます。vite dev では一切出ません。

▲ [WARNING] [ignored-bare-import] Ignoring require() of module "node:events" which is a bundled Node module
▲ [WARNING] [ignored-bare-import] Ignoring require() of module "node:stream" which is a bundled Node module
▲ [WARNING] [ignored-bare-import] Ignoring require() of module "node:util" which is a bundled Node module
（以下, 同様の警告が続く）

【原因】

Cloudflare Workers の SSR ビルド時、Node.js ビルトインモジュール（node:events、node:stream など）の bare import が SSR バンドルに混入します。wrangler pages dev はこの bare import を警告として検出しますが、vite dev は Node.js ネイティブ環境で動作するため警告が出ません。

React Router v7 への移行やパッケージのアップデートにより、wrangler のバージョンが上がると警告の粒度が変わることがあるため、移行のタイミングで再確認が必要です。

【対処コード】

カスタム Vite プラグイン removeNodeBareImports で、SSR バンドルから bare import を除去します。ソースマップを壊さない実装になっています。

Workers環境では node: モジュールは存在しないため
require 呼び出しは実行されない

// vite.config.ts に追加するプラグイン

function removeNodeBareImports(): Plugin {
  return {
    name: "remove-node-bare-imports",
    // SSRビルド時のみ適用
    apply: "build",
    generateBundle(_options, bundle) {
      for (const [, chunk] of Object.entries(bundle)) {
        if (chunk.type !== "chunk") continue;
        // SSRエントリのバンドルのみ対象
        if (!chunk.isEntry) continue;
        // node: プレフィックスのbareインポートを除去
        chunk.code = chunk.code.replace(
          /require\(["']node:[^"']+["']\);?\n?/g,
          ""
        );
      }
    },
  };
}

vite.config.ts の plugins 配列に追加します。

// vite.config.ts
import { reactRouter } from "@react-router/dev/vite";
import { cloudflareDevProxy } from "@react-router/dev/vite/cloudflare";

export default defineConfig({
  plugins: [
    cloudflareDevProxy(),
    reactRouter(),
    removeNodeBareImports(), // SSRバンドルのbare import除去
  ],
});

警告はビルドの動作に影響しませんが、大量に出力されると本当に必要な警告を見落とすリスクがあります。移行計画にこのプラグイン追加を含めておくことで、混乱なく対処できます。

⚠️ 作業2: Windows × wrangler キャッシュロック問題への対処

【症状（Windows のみ）】

wrangler pages dev でビルド成果物を更新したにもかかわらず、ブラウザに古い画面が表示され続けます。サーバーを再起動しても変わりません。

【原因】

.wrangler/state/v3 ディレクトリ内の SQLite ファイル（miniflare-*.sqlite）が Node.js プロセスにロックされ、ビルド成果物の変更が反映されなくなります。

Windows のファイルシステムはプロセスが終了してもファイルロックが残ることがあり、この挙動は Mac / Linux では発生しません。React Router v7 へのアップデートでビルド成果物の構造が変わると、特にこの問題が顕在化しやすくなります。

【対処コード】

クリーンアップスクリプト scripts/clean-wrangler-cache.sh をコードベースに用意します。

#!/bin/bash
# scripts/clean-wrangler-cache.sh
# Windows × wrangler のキャッシュロック問題を解消する

WRANGLER_STATE=".wrangler/state/v3"

if [ -d "$WRANGLER_STATE" ]; then
  echo "Cleaning wrangler state cache..."
  rm -rf "$WRANGLER_STATE"
  echo "Done. Restart 'wrangler pages dev' to apply changes."
else
  echo "No wrangler state cache found. Nothing to clean."
fi

package.json にスクリプトを追加しておくと、チームメンバーが即座に実行できます。

{
  "scripts": {
    "clean:wrangler": "bash scripts/clean-wrangler-cache.sh"
  }
}

問題が発生したら npm run clean:wrangler を実行し、その後 wrangler pages dev を再起動します。このスクリプトを移行計画に含めておけば、「変更が反映されない」という状況で慌てずに対処できます。

🎓 学んだこと・まとめ

技術的な学び

【wrangler pages dev は vite dev とは別の問題を持つ】: 同じコードでも実行環境が変わると別の問題が出る。両方で動作確認することが移行の完了条件
【bare import 警告は無害だが見落としを生む】: 警告自体は動作に影響しないが、大量に出ると本当に必要な警告を見落とすリスクがある
【Windows 固有の問題はチームに明示が必要】: キャッシュロック問題は Windows 開発者だけが遭遇する。Mac/Linux メンバーには発生しないため、原因不明のまま時間を失いやすい

移行計画への組み込みチェックリスト

移行タスクリストに以下を最初から含めておきます。

removeNodeBareImports Vite プラグインを vite.config.ts に追加
scripts/clean-wrangler-cache.sh をコードベースに配置
package.json に clean:wrangler スクリプトを追加
Windows 開発者にキャッシュロック問題の存在を周知

今後のベストプラクティス

問題が起きてから対処するのか、計画に入れておくのかで、移行の印象はまったく変わります。「予期せぬ作業」は計画の精度の問題であり、コードの問題ではありません。2点を最初から計画に入れておけば、どちらも「移行タスクの一項目として淡々と完了する」作業になります。

同じような問題で困っている方の参考になれば幸いです！

このwrangler環境問題の前段として、React Router v7移行後にtypecheckが壊れる4つの原因と修正コードも合わせて把握しておくと、移行作業全体のスコープが見えてきます。また、wranglerのキャッシュ問題は本質的にD1ローカル環境を「決定論的空間」として設計するという課題と同根です。.wranglerディレクトリを状態管理の対象として捉え直すことで、より根本的な解決策が見えてきます。