cra-to-next-migration

CRA から Next.js への移行ガイド

Create React App プロジェクトを Next.js に移行するための包括的なガイドです。ルーティング、データ取得、コンポーネント、スタイリング、デプロイを取り上げます。移行の影響度に応じて優先順位付けされた、17 のカテゴリーにわたる 148 のルールが含まれています。移行が正常に完了した後も、アプリケーションは移行前と同じように動作する必要があります。

適用するタイミング

次のような場合に、これらのガイドラインを参照してください。

• 既存の CRA アプリケーションを Next.js に移行する
• React Router のルートをファイルベースのルーティングに変換する
• クライアント中心のアプリで Server Components を採用する
• クライアントサイドレンダリングから SSR／SSG に移行する
• Next.js 用に環境変数を更新する
• Next.js 組み込みの機能で画像やフォントを最適化する

バージョンポリシー

Next.js 16.x 以降を使用してください。Next.js 14.x または 15.x は使用しないでください。

移行を始める前に、現在の最新バージョンを確認してください。

npm info next version

minor／patch アップデート用にキャレットを付け、package.json には最新バージョンを使用してください。この移行ガイドでサポートされる最小バージョンは ^16.0.0 です。

優先度別のルールカテゴリー

優先度	カテゴリー	影響度	プレフィックス	ルール数
1	プロジェクトのセットアップ	CRITICAL	setup-	6
2	依存関係	CRITICAL	deps-	1
3	ルーティング	CRITICAL	routing-	17
4	データ取得	CRITICAL	data-	11
5	コンポーネント	HIGH	components-	9
6	環境変数	HIGH	env-	6
7	スタイリング	HIGH	styling-	12
8	パブリックアセット	MEDIUM	assets-	5
9	画像	MEDIUM	images-	8
10	フォント	MEDIUM	fonts-	6
11	SEO とメタデータ	MEDIUM	seo-	9
12	API ルート	MEDIUM	api-	9
13	状態管理	MEDIUM	state-	8
14	インテグレーション	MEDIUM	integrations-	1
15	テスト	LOW	testing-	9
16	ビルドとデプロイ	LOW	build-	7
17	よくある落とし穴	HIGH	gotchas-	24

クイックリファレンス

1. プロジェクトのセットアップ（CRITICAL）

• setup-initial-structure - CRA のフォルダー構造を Next.js App Router に変換する
• setup-package-json - 依存関係とスクリプトを更新する
• setup-next-config - next.config.js を作成して設定する
• setup-typescript - TypeScript の設定を移行する
• setup-eslint - Next.js 用に ESLint を更新する
• setup-gitignore - Next.js 用に .gitignore を更新する

2. 依存関係（CRITICAL）

• deps-react19-compatibility - React 19 との互換性のために依存関係をアップグレードする

3. ルーティング（CRITICAL）

• routing-basic-pages - コンポーネントをファイルベースのルートに変換します
• routing-dynamic-routes - 動的セグメントには [param] 構文を使用します
• routing-catch-all-routes - キャッチオールルートには [...slug] を使用します
• routing-optional-catch-all - オプションのキャッチオールには [[...slug]] を使用します
• routing-route-groups - 整理には (group) フォルダーを使用します
• routing-parallel-routes - 並列ルートには @slot を使用します
• routing-intercepting-routes - インターセプトルートには (..) を使用します
• routing-link-component - react-router の Link を next/link に置き換えます
• routing-programmatic-navigation - useNavigate を useRouter に置き換えます
• routing-use-params - useParams を Next.js の params に置き換えます
• routing-use-search-params - useSearchParams を適切に置き換えます
• routing-nested-layouts - ネストされたルートをレイアウトに変換します
• routing-loading-states - サスペンス用に loading.tsx を追加します
• routing-error-boundaries - エラー処理用に error.tsx を追加します
• routing-not-found - 404 ページ用に not-found.tsx を追加します
• routing-hash-based - クライアント専用アプリのハッシュベースルーティングに対応します
• routing-protected-routes - 保護されたルートのパターンを実装します

4. データ取得（CRITICAL）

• data-useeffect-to-rsc - useEffect によるデータ取得をサーバーコンポーネントに変換します
• data-useeffect-to-ssr - useEffect を getServerSideProps に変換します
• data-useeffect-to-ssg - useEffect を getStaticProps に変換します
• data-client-fetch - 適切なパターンを使ってクライアント側のデータ取得を維持します
• data-server-actions - データ変更にはサーバーアクションを使用します
• data-revalidation - データ再検証の戦略を設定します
• data-streaming - データのストリーミングには Suspense を使用します
• data-parallel-fetching - サーバー上でデータを並列に取得します
• data-sequential-fetching - データの順次依存関係を処理します
• data-caching - fetch のキャッシュ動作を設定します
• data-client-library-init - useEffect 内でクライアント専用ライブラリを初期化します

5. コンポーネント（HIGH）

• components-use-client - クライアントコンポーネントには 'use client' ディレクティブを追加します
• components-server-default - サーバーコンポーネントがデフォルトであることを理解します
• components-boundary-placement - クライアント境界を戦略的に配置します
• components-composition - クライアント側の JavaScript を最小限に抑えるため、コンポジションを使用します
• components-interleaving - サーバーコンポーネントとクライアントコンポーネントを交互に配置します
• components-props-serialization - props がシリアライズ可能であることを確認します
• components-children-pattern - サーバーコンポーネントを子として渡します
• components-context-providers - Context プロバイダーを適切に処理します
• components-third-party - サードパーティのクライアントコンポーネントをラップします

6. 環境変数（HIGH）

• env-prefix-change - REACTAPP を NEXTPUBLIC に変更します
• env-server-only - サーバー専用にはプレフィックスのない変数を使用します
• env-runtime-config - 必要に応じてランタイム設定を使用します
• env-local-files - .env ファイルの読み込み順序を理解します
• env-build-time - ビルド時と実行時の環境変数の違いを理解します
• env-validation - 必須の環境変数を検証します

7. スタイリング（HIGH）

• styling-global-css - グローバル CSS を app/layout.tsx に移動します
• styling-css-modules - CSS Modules はわずかな変更で動作します
• styling-sass - Sass のサポートを設定します
• styling-tailwind - Tailwind CSS を設定します
• styling-css-in-js - CSS-in-JS ライブラリに対応します
• styling-styled-components - SSR 用に styled-components を設定します
• styling-emotion - SSR 用に Emotion を設定します
• styling-component-styles - コンポーネントのスタイルを適切にインポートします
• styling-postcss - PostCSS を設定します
• styling-scss-global-syntax - :global は CSS Modules 内でのみ使用します
• styling-css-import-order - レイアウト内の CSS のインポート順序を制御します
• styling-dark-mode-hydration - ハイドレーションの不一致を起こさずにダークモードに対応します

8. 公開アセット（MEDIUM）

• assets-public-folder - public フォルダーは同じように動作します
• assets-static-imports - アセットには静的インポートを使用します
• assets-absolute-urls - public プレフィックスを付けずにアセットを参照します
• assets-favicon - favicon を app ディレクトリに配置します
• assets-manifest - ウェブアプリマニフェストを設定します

9. 画像（MEDIUM）

• images-next-image - img を next/image に置き換える
• images-required-dimensions - width と height を指定する
• images-fill-prop - レスポンシブ画像には fill を使用する
• images-priority - LCP 画像には priority を使用する
• images-placeholder - ぼかしプレースホルダーを設定する
• images-remote-patterns - リモート画像のドメインを設定する
• images-loader - カスタム画像ローダーを設定する
• images-optimization - 自動最適化について理解する

10. フォント（MEDIUM）

• fonts-next-font - 最適化には next/font を使用する
• fonts-google-fonts - Google Fonts を適切に読み込む
• fonts-local-fonts - ローカルフォントファイルを読み込む
• fonts-variable-fonts - 可変フォントを設定する
• fonts-font-display - font-display 戦略を設定する
• fonts-preload - フォントの自動プリロードについて理解する

11. SEO とメタデータ（MEDIUM）

• seo-metadata-api - react-helmet ではなく Metadata API を使用する
• seo-dynamic-metadata - 動的なメタデータを生成する
• seo-opengraph - Open Graph メタデータを設定する
• seo-twitter-cards - Twitter Card メタデータを設定する
• seo-json-ld - 構造化データ（JSON-LD）を追加する
• seo-canonical - canonical URL を設定する
• seo-robots - robots メタタグを設定する
• seo-sitemap - sitemap.xml を生成する
• seo-head-component - next/head から Metadata へ移行する

12. API ルート（MEDIUM）

• api-route-handlers - app/api に Route Handlers を作成する
• api-http-methods - HTTP メソッド用の名前付き関数をエクスポートする
• api-request-body - リクエストボディを適切に解析する
• api-query-params - クエリパラメーターにアクセスする
• api-headers-cookies - ヘッダーと Cookie にアクセスする
• api-response-types - 適切なレスポンスタイプを返す
• api-middleware - ミドルウェアのパターンを実装する
• api-cors - CORS を適切に設定する
• api-rate-limiting - レート制限を実装する

13. 状態管理（MEDIUM）

• state-context-client - Context には 'use client' が必要
• state-zustand - Zustand はハイドレーションに注意して使用する
• state-redux - Next.js 用に Redux を設定する
• state-jotai - Jotai を適切に設定する
• state-recoil - Recoil を適切に設定する
• state-url-state - 共有可能な状態には URL を使用する
• state-server-state - RSC でクライアント側の状態を最小限に抑える
• state-persistence - 状態の永続化を処理する

14. インテグレーション（MEDIUM）

• integrations-sentry - Sentry のエラー監視を移行する

15. テスト（LOW）

• testing-jest-config - Jest の設定を更新する
• testing-react-testing-library - RTL は同じように動作する
• testing-server-components - Server Components をテストする
• testing-client-components - Client Components をテストする
• testing-async-components - 非同期コンポーネントをテストする
• testing-mocking - Next.js モジュールをモックする
• testing-e2e-cypress - Next.js 用に Cypress を設定する
• testing-e2e-playwright - Next.js 用に Playwright を設定する
• testing-api-routes - API Route Handlers をテストする

16. ビルドとデプロイ（LOW）

• build-scripts - ビルドスクリプトを更新する
• build-output - ビルド出力について理解する
• build-standalone - スタンドアロン出力を設定する
• build-static-export - 静的エクスポートを設定する
• build-bundle-analysis - バンドルサイズを分析する
• build-vercel - Vercel にデプロイする
• build-docker - Docker のデプロイを設定する

17. よくある落とし穴（HIGH）

• gotchas-window-undefined - SSR で window/document を扱う
• gotchas-hydration-mismatch - ハイドレーションの不一致を修正する
• gotchas-use-effect-timing - Next.js で useEffect を理解する
• gotchas-router-ready - クエリパラメーターには router.isReady を確認する
• gotchas-dynamic-imports - next/dynamic を適切に使用する
• gotchas-api-routes-edge - Edge と Node.js のランタイム
• gotchas-middleware - ミドルウェアはエッジで実行される
• gotchas-static-generation - 静的レンダリングと動的レンダリング
• gotchas-redirect - リダイレクトを適切に処理する
• gotchas-headers - レスポンスヘッダーを設定する
• gotchas-cookies - RSC で Cookie を扱う
• gotchas-turbopack - Turbopack の互換性に関する問題を扱う
• gotchas-empty-modules - isolatedModules の空のモジュールエクスポートを修正する
• gotchas-nullish-coalescing - Nullish coalescing の実行時エラーを修正する
• gotchas-react19-class-components - React 19 のクラスコンポーネントの this バインディングを修正する
• gotchas-react19-ref-prop - React 19 の ref プロパティの変更に対応する
• gotchas-websocket-optional-deps - WebSocket のネイティブ依存関係のバンドルに対応する
• gotchas-auth-race-conditions - 認証/API の競合状態を防ぐ
• gotchas-auth-state-gating - ロールを確認する前に認証状態を待つ
• gotchas-configuration-idempotency - useRef で設定の冪等性を確保する
• gotchas-hydration-nested-interactive - インタラクティブ要素の入れ子を避ける
• gotchas-router-push-timing - レンダリング中に router.push を呼び出さない
• gotchas-infinite-rerender - 無限の再レンダリングループを防ぐ
• gotchas-provider-hierarchy - プロバイダーの階層を正しく設定する

移行前チェックリスト

移行を始める前に、特別な対応が必要なパターンがないかコードベースをスキャンします。

# Check for WebSocket libraries (needs webpack fallback config)
grep -E "(socket\.io|\"ws\")" package.json

# Check for SCSS :export syntax (may need --webpack flag)
grep -r ":export" --include="*.scss" src/

# Check for SVG ReactComponent imports (needs SVGR config)
grep -r "ReactComponent" --include="*.ts" --include="*.tsx" src/

# List all REACT_APP_ environment variables
grep -roh "REACT_APP_[A-Z_]*" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" src/ | sort -u

# Check for Redux extraReducers using object notation (must convert to builder pattern for RTK v2)
grep -r "extraReducers:" --include="*.js" --include="*.jsx" --include="*.ts" --include="*.tsx" src/

# Check for /app/ paths that need updating if using (app) route group
grep -rE "(href|to|push|replace|redirect).*['\"]\/app\/" --include="*.js" --include="*.jsx" --include="*.ts" --include="*.tsx" src/

スキャン結果と参照ルール：

スキャン結果	読むべきルール
package.json に socket.io または ws がある	gotchas-websocket-optional-deps, setup-next-config
SCSS ファイルに :export がある	gotchas-turbopack
ReactComponent SVG インポート	assets-static-imports
REACT_APP_ 変数が見つかった	env-prefix-change
extraReducers: が見つかった	state-redux（RTK v2 では builder コールバックが必要）
ナビゲーションに /app/ パスがある	routing-route-groups（ルートグループに合わせてパスを更新）

使用方法

詳しい説明とコード例については、個々のルールファイルを読んでください。

rules/setup-initial-structure.md
rules/routing-basic-pages.md
rules/data-useeffect-to-rsc.md

各ルールファイルには、次の内容が含まれています。

• 移行手順の簡単な説明
• CRA の「移行前」コード例
• Next.js の「移行後」コード例
• 補足情報と注意点

移行の順序

最良の結果を得るには、次の順序で移行してください。

1. セットアップ - Next.js のプロジェクト構成を初期化する
2. ルーティング - React Router をファイルベースのルーティングに変換する
3. 環境変数 - 環境変数のプレフィックスを更新する
4. コンポーネント - 必要な箇所に 'use client' ディレクティブを追加する
5. データ取得 - useEffect をサーバーパターンに変換する
6. スタイリング - グローバル CSS を移動し、CSS-in-JS を設定する
7. 画像とフォント - Next.js の最適化を採用する
8. SEO - Metadata API に移行する
9. API ルート - Route Handlers を作成する
10. テスト - テスト設定を更新する

移行後の検証チェックリスト

移行後、アプリケーションが正しく動作することを確認します。

コア機能：

• npm run dev でエラーなく Next.js 開発サーバーが起動する
• npm run build が正常に完了する
• npm start で本番ビルドが実行される
• メインアプリケーションが正しく表示される
• すべてのルートにアクセスできる

クライアント側の機能：

• localStorage/sessionStorage による永続化が機能する
• ダークモードまたはテーマの切り替えが機能し、設定が保持される
• クライアント側のインタラクティブ機能（フォーム、ボタン、モーダル）が機能する
• ブラウザーの戻る／進むナビゲーションが正しく機能する

ルーティング（該当する場合）：

• ハッシュベースのルーティングが機能する（例：#room=abc,key=xyz）
• クエリパラメーターが正しく読み取られる
• 動的ルートが正しいパラメーターで表示される
• 無効なルートで 404 ページが表示される

リアルタイム機能（該当する場合）：

• WebSocket 接続が正常に確立される
• リアルタイムの共同作業または更新が機能する
• 切断後の再接続が機能する

インテグレーション（該当する場合）：

• エラー監視（Sentry）でエラーが捕捉される
• 分析トラッキングが正しく実行される
• サードパーティー認証（OAuth、Firebase）が機能する
• ファイルのアップロードが機能する

PWA（該当する場合）：

• サービスワーカーが登録される（本番ビルド）
• アプリをインストールできる
• オフライン機能が想定どおりに動作する

パフォーマンス：

• コンソールにハイドレーションの不一致に関する警告が表示されない
• 画像が読み込まれ、最適化されている
• FOUT/FOIT の問題なくフォントが読み込まれる
• 予期しないコンソールエラーや警告がない