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 本体に取り込まれた。

どちらの背景から来ても、何らかの変更対応が必要になる。


原因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 から移行する際の確認リスト。


まとめ

React Router v7 で動かない原因は大きく5つだ。

  1. 型ファイルが生成されていない → npx react-router typegen を実行する
  2. useLoaderData() の型が any → Route.ComponentProps の loaderData props を使う
  3. clientLoader でハイドレーションが壊れる → hydrateFallback を追加する
  4. defer / Await が消えた → Promise をそのまま返して use() + Suspense で受け取る
  5. Remix のパッケージ名が残っている → @remix-run/* を react-router / @react-router/* に変更する

特に 型ファイルの自動生成(typegen) を知らずに移行すると、型が全部 any になって TypeScript の恩恵が消えてしまう。Framework モードを使っているなら必ず react-router typegen を CI に組み込もう。

技術ブログの記事一覧へ