React Router v7 で動かない・型エラーになる時の対処法:v6 / Remix からの移行で詰まる5つの原因
公開日:2026-07-04/カテゴリ:React・React Router・Remix・TypeScript/AnchorUp 技術ブログ
React Router v7 で動かない時に確認すること(結論)
React Router v7(2024年11月リリース)は v6 とも Remix v2 とも大きく変わっており、移行後にエラーが出るケースが多い。よく起きるトラブルと対策を先にまとめる。
| 症状 | 原因 | 対策 |
|---|---|---|
useLoaderData() の型が any になる |
Route モジュール型の参照方法が変わった | Route.LoaderArgs / Route.ComponentProps を使う |
Cannot find module '+types/...' |
型ファイルの自動生成が未実行 | react-router typegen を実行する |
clientLoader の実行順序がおかしい |
hydrateFallback の実装漏れ |
hydrateFallback コンポーネントを追加する |
defer / Await が動かない |
v7 で廃止、Promise 直接返却に変更 | loader から Promise をそのまま return する |
createBrowserRouter のオプションが変わった |
Framework モードと Library モードの違い | 使用モードを確認し設定を合わせる |
なぜ React Router v7 は破壊的変更が多いのか
React Router v7 は事実上 Remix v3 として設計されており、Remix のファイルベースルーティングと型安全なデータローダーの仕組みが Router 本体に取り込まれた。
- v6 ユーザー: データローダー(loader/action)の型推論が大きく変わった
- Remix v2 ユーザー:
@remix-run/reactからreact-routerへの移行が必要になった
どちらの背景から来ても、何らかの変更対応が必要になる。
原因1: useLoaderData() の型が any になる(最多)
React Router v7 では型安全なデータアクセスのために Route Module Types(型自動生成) という仕組みが導入された。これを使わないと useLoaderData() の返り値が any になる。
v6 での書き方(非推奨)
// v6 での型付け(v7でも動くが型が any になる)
import { useLoaderData } from 'react-router'
export async function loader() {
return { user: { name: 'Taro', age: 30 } }
}
export default function UserPage() {
const data = useLoaderData() // ← v7 では型が any になる
return <div>{data.user.name}</div>
}
v7 での正しい書き方
# 型ファイルを生成する(初回 & ルートファイル変更後に実行)
npx react-router typegen
// app/routes/user.tsx
import type { Route } from './+types/user' // ← 自動生成された型ファイル
export async function loader({ params }: Route.LoaderArgs) {
return { user: { name: 'Taro', age: 30 } }
}
export default function UserPage({ loaderData }: Route.ComponentProps) {
// loaderData が { user: { name: string; age: number } } として推論される
return <div>{loaderData.user.name}</div>
}
Route.ComponentProps を使うことで useLoaderData() を呼ばずとも loaderData が props として受け取れる。型も完全に推論される。
react-router typegenが見つからない場合:package.jsonのscriptsに"typecheck": "react-router typegen && tsc"を追加して、型生成を TypeScript チェックの前工程として組み込むと良い。
原因2: Cannot find module './+types/FileName' エラー
react-router typegen を一度も実行していない、または実行が古い状態だと、上記の型ファイルが存在せずビルドエラーになる。
error TS2307: Cannot find module './+types/user' or its corresponding type declarations.
対策
# 1. 型ファイルを生成
npx react-router typegen
# 2. .gitignore に追加(自動生成なのでコミット不要)
echo ".react-router/" >> .gitignore
{
"scripts": {
"dev": "react-router dev",
"build": "react-router build",
"typecheck": "react-router typegen && tsc"
}
}
CI でも typecheck スクリプトを使えば typegen が先に走るため、型ファイルのコミット漏れを気にしなくて良くなる。
原因3: clientLoader でハイドレーションが壊れる
React Router v7 では clientLoader を使う際に hydrateFallback の実装が必要な場面がある。実装を忘れると SSR 時にコンポーネントがハイドレーション不一致でクラッシュする。
Error: Hydration failed because the initial UI does not match what was rendered on the server.
問題のあるコード
// ❌ hydrateFallback がない場合、SSR とクライアントの表示が一致しない
export async function clientLoader() {
const data = await fetch('/api/user').then(r => r.json())
return data
}
export default function UserPage({ loaderData }: Route.ComponentProps) {
return <div>{loaderData.name}</div>
}
修正後
// ✅ hydrateFallback を追加してSSR時のフォールバックを明示する
export async function clientLoader() {
const data = await fetch('/api/user').then(r => r.json())
return data
}
// SSR(ハイドレーション前)に表示するコンポーネント
export function hydrateFallback() {
return <div>Loading...</div>
}
export default function UserPage({ loaderData }: Route.ComponentProps) {
return <div>{loaderData.name}</div>
}
clientLoader は クライアント側でのみ実行される データ取得で、サーバーで loader を走らせたくない場合に使う。ハイドレーション前はサーバーレンダリング結果が表示されるため、その間のフォールバックが必要だ。
原因4: defer と Await が使えなくなった
Remix v2 や React Router v6.4 以降の一部で使えた defer / Await パターンが、React Router v7 では廃止された。
// ❌ v7 では動かない
import { defer, Await } from 'react-router'
export async function loader() {
const fastData = await fetchFast()
const slowData = fetchSlow() // await しない
return defer({ fastData, slowData }) // defer は削除された
}
export default function Page({ loaderData }) {
return (
<Suspense fallback={<div>Loading slow data...</div>}>
<Await resolve={loaderData.slowData}>
{(data) => <div>{data.title}</div>}
</Await>
</Suspense>
)
}
v7 での代替パターン
v7 では loader から Promise をそのまま返すことで同等の遅延読み込みが実現できる。
// ✅ v7 での遅延読み込み
export async function loader() {
const fastData = await fetchFast()
const slowDataPromise = fetchSlow() // Promise を保持
return { fastData, slowDataPromise } // Promise をそのまま返す
}
export default function Page({ loaderData }: Route.ComponentProps) {
return (
<div>
<div>{loaderData.fastData.title}</div>
{/* React の use() フックで Promise を解決する */}
<Suspense fallback={<div>Loading...</div>}>
<SlowSection promise={loaderData.slowDataPromise} />
</Suspense>
</div>
)
}
function SlowSection({ promise }: { promise: Promise<SlowData> }) {
const data = use(promise) // React 19 の use() フック
return <div>{data.description}</div>
}
use() は React 19 以降で使えるフックで、Promise や Context を直接受け取れる。Suspense と組み合わせることで Await と同等の動作が実現できる。
原因5: Remix v2 から移行する際のパッケージ変更漏れ
Remix v2 から React Router v7 へ移行する際、パッケージ名の変更が必要だ。変更が不完全だと型エラーや実行時エラーが出る。
変更が必要なパッケージ
# 削除するパッケージ
npm uninstall @remix-run/react @remix-run/node @remix-run/serve @remix-run/dev
# 追加するパッケージ
npm install react-router @react-router/node @react-router/serve
npm install -D @react-router/dev
import パスの変更
// ❌ 変更前(Remix)
import { useLoaderData, Form, Link } from '@remix-run/react'
import type { LoaderFunctionArgs } from '@remix-run/node'
// ✅ 変更後(React Router v7)
import { useLoaderData, Form, Link } from 'react-router'
import type { LoaderFunctionArgs } from 'react-router'
vite.config.ts の変更
// ❌ 変更前
import { vitePlugin as remix } from '@remix-run/dev'
export default defineConfig({
plugins: [remix()],
})
// ✅ 変更後
import { reactRouter } from '@react-router/dev/vite'
export default defineConfig({
plugins: [reactRouter()],
})
Framework モード vs Library モードの確認
React Router v7 には2つの使い方がある。混乱の元になるため自分のプロジェクトがどちらかを確認しよう。
| モード | 説明 | ファイルベースルーティング | 型自動生成 |
|---|---|---|---|
| Framework モード | Vite プラグイン + app/ ディレクトリ構成 |
あり(デフォルト) | あり(typegen コマンド) |
| Library モード | createBrowserRouter を自前で使う |
なし(手動設定) | なし |
Framework モードを使っていない(@react-router/dev の Vite プラグインを使っていない)場合、Route.LoaderArgs などの型ファイルは生成されない。Library モードでは v6 と同様に手動で型を書く必要がある。
# Framework モードかどうかの確認
cat vite.config.ts | grep react-router
# → "reactRouter" が含まれていれば Framework モード
移行チェックリスト
Remix v2 または React Router v6 から移行する際の確認リスト。
- [ ]
@remix-run/*パッケージをreact-router/@react-router/*に変更した - [ ]
vite.config.tsのプラグインをreactRouter()に変更した - [ ]
react-router typegenを実行して型ファイルを生成した - [ ]
useLoaderData()の代わりにRoute.ComponentPropsのloaderDataを使っている - [ ]
defer/AwaitをPromise+use()/Suspenseに書き換えた - [ ]
clientLoaderを使うルートにhydrateFallbackを追加した - [ ] CI の typecheck スクリプトに
react-router typegenを追加した
まとめ
React Router v7 で動かない原因は大きく5つだ。
- 型ファイルが生成されていない →
npx react-router typegenを実行する useLoaderData()の型がany→Route.ComponentPropsのloaderDataprops を使うclientLoaderでハイドレーションが壊れる →hydrateFallbackを追加するdefer/Awaitが消えた → Promise をそのまま返してuse()+Suspenseで受け取る- Remix のパッケージ名が残っている →
@remix-run/*をreact-router/@react-router/*に変更する
特に 型ファイルの自動生成(typegen) を知らずに移行すると、型が全部 any になって TypeScript の恩恵が消えてしまう。Framework モードを使っているなら必ず react-router typegen を CI に組み込もう。