React Router v7 移行で typecheck が壊れる4つの原因(Remix v2 → v7)

著者: ClaudeMix Team |

React Router v7(2024年11月リリース)は Remix v2 との互換性を意識して設計されているが、移行後にnpm run typecheckを実行すると4点で型エラーが発生する。いずれも「コードのバグ」ではなく、APIの仕様変更・型定義の消失が原因。

症状

  • 発生環境: React Router v7.13.1(移行前: Remix v2) / Cloudflare Pages・Workers / Vite / TypeScript
  • ビルドは通るがtypecheckが通らない

原因と解決策

1. `json()` ヘルパーの廃止

Module '"react-router"' has no exported member 'json'.

Single Fetchがデフォルトになり、json()がreact-routerから削除された。

- import { json } from "@remix-run/cloudflare";
+ import { data as json } from "react-router";

data()はjson()と同じシグネチャのため、呼び出し箇所の変更は不要。

2. `react-dom/server.browser` の型定義不在

Could not find a declaration file for module 'react-dom/server.browser'.

Cloudflare Workers(Edge Runtime)ではrenderToReadableStreamを含むreact-dom/server.browserが必要だが、@react-router/cloudflareへの移行後に型定義が消える。Edge固有の問題で、公式ドキュメントに記載はない。

// app/react-dom-server-browser.d.ts(新規作成)
declare module "react-dom/server.browser" {
  export { renderToReadableStream } from "react-dom/server";
}

3. tsconfig の `types` エントリ変更

@remix-run/devが担っていた型定義注入が、.react-router/types/への自動生成方式に変わった。

// tsconfig.json
{
  "compilerOptions": {
-   "types": ["@remix-run/dev", "vite/client"]
+   "types": ["vite/client"]
  },
  "include": [
    "/*.ts", "/*.tsx",
+   ".react-router/types//*"
  ]
}

4. `ServerRouter` の `abortDelay` prop 廃止

// app/entry.server.tsx
- import { RemixServer } from "@remix-run/react";
+ import { ServerRouter } from "react-router";
  const body = await renderToReadableStream(
-   <RemixServer context={remixContext} url={request.url} abortDelay={5000} />,
+   <ServerRouter context={routerContext} url={request.url} />,
    { signal: controller.signal }
  );

タイムアウト制御はAbortControllerのsetTimeout+controller.abort()で行う。

4点とも、このブログ自身(React Router × Cloudflare Edge、802テスト全パス)で本番検証済み。

学び

  • 4点とも「コードのバグ」ではなく仕様変更が原因。移行前にこのチェックリストを把握しておけば、AIエージェントに移行作業を委任する際の手戻り(権限確認の連発、コンテキスト消費)を防げる
  • 移行完了の定義は「ビルドが通る」ではなく「typecheckも通る」にする
  • wrangler環境固有の後続問題はReact Router v7移行後、wrangler pages devで起きる2つの環境問題に記録した