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

package.json で最新バージョンを使用し、マイナーおよびパッチ更新用にキャレット (^) を付けます。このガイドの最小サポートバージョンは ^16.0.0 です。

ルールカテゴリー（優先度順）

優先度	カテゴリー	影響度	プレフィックス	ルール数
1	Project Setup	CRITICAL	setup-	6
2	Dependencies	CRITICAL	deps-	1
3	Routing	CRITICAL	routing-	17
4	Data Fetching	CRITICAL	data-	11
5	Components	HIGH	components-	9
6	Environment Variables	HIGH	env-	6
7	Styling	HIGH	styling-	12
8	Public Assets	MEDIUM	assets-	5
9	Images	MEDIUM	images-	8
10	Fonts	MEDIUM	fonts-	6
11	SEO & Metadata	MEDIUM	seo-	9
12	API Routes	MEDIUM	api-	9
13	State Management	MEDIUM	state-	8
14	Integrations	MEDIUM	integrations-	1
15	Testing	LOW	testing-	9
16	Build & Deploy	LOW	build-	7
17	Common Gotchas	HIGH	gotchas-	24

クイックリファレンス

1. Project Setup (CRITICAL)

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

2. Dependencies (CRITICAL)

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

3. Routing (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 - suspense 用の loading.tsx を追加
• routing-error-boundaries - エラーハンドリング用の error.tsx を追加
• routing-not-found - 404 ページ用の not-found.tsx を追加
• routing-hash-based - クライアントのみのアプリのハッシュベースのルーティングを処理
• routing-protected-routes - 保護されたルートパターンを実装

4. Data Fetching (CRITICAL)

• data-useeffect-to-rsc - useEffect フェッチを Server Components に変換
• data-useeffect-to-ssr - useEffect を getServerSideProps に変換
• data-useeffect-to-ssg - useEffect を getStaticProps に変換
• data-client-fetch - 適切なパターンでクライアントフェッチを保持
• data-server-actions - Server Actions をミューテーション用に使用
• data-revalidation - データ再検証戦略を構成
• data-streaming - データストリーミング用に Suspense を使用
• data-parallel-fetching - サーバーで並行してデータをフェッチ
• data-sequential-fetching - 順序付きデータの依存関係を処理
• data-caching - フェッチキャッシング動作を構成
• data-client-library-init - useEffect でクライアントのみのライブラリを初期化

5. Components (HIGH)

• components-use-client - クライアントコンポーネント用に 'use client' ディレクティブを追加
• components-server-default - Server Components がデフォルトであることを理解
• components-boundary-placement - クライアント境界を戦略的に配置
• components-composition - コンポジションを使用して클라이언트 JS を最小化
• components-interleaving - Server Components と Client Components をインターリーブ
• components-props-serialization - props がシリアル化可能であることを確認
• components-children-pattern - Server Components を children として渡す
• components-context-providers - Context プロバイダーを適切に処理
• components-third-party - サードパーティのクライアントコンポーネントをラップ

6. Environment Variables (HIGH)

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

7. Styling (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 - CSS Modules では :global のみを使用
• styling-css-import-order - レイアウト内の CSS インポート順序を制御
• styling-dark-mode-hydration - ハイドレーションミスマッチなしでダークモードを処理

8. Public Assets (MEDIUM)

• assets-public-folder - Public フォルダは同じ方法で動作
• assets-static-imports - アセット用に static import を使用
• assets-absolute-urls - public プレフィックスなしでアセットを参照
• assets-favicon - favicon を app ディレクトリに配置
• assets-manifest - Web App Manifest を構成

9. Images (MEDIUM)

• images-next-image - img を next/image に置き換え
• images-required-dimensions - width と height を提供
• images-fill-prop - レスポンシブ画像用に fill を使用
• images-priority - LCP 画像用に priority を使用
• images-placeholder - blur プレースホルダーを構成
• images-remote-patterns - リモート画像ドメインを構成
• images-loader - カスタム画像ローダーを構成
• images-optimization - 自動最適化を理解

10. Fonts (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 & Metadata (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 - 正規 URL を設定
• seo-robots - robots メタタグを構成
• seo-sitemap - sitemap.xml を生成
• seo-head-component - next/head から Metadata に移行

12. API Routes (MEDIUM)

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

13. State Management (MEDIUM)

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

14. Integrations (MEDIUM)

• integrations-sentry - Sentry エラーモニタリングを移行

15. Testing (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. Build & Deployment (LOW)

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

17. Common Gotchas (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 vs Node.js ランタイム
• gotchas-middleware - ミドルウェアは Edge で実行
• gotchas-static-generation - 静的とダイナミックレンダリング
• gotchas-redirect - リダイレクトを適切に処理
• gotchas-headers - レスポンスヘッダーを設定
• gotchas-cookies - RSC でクッキーを処理
• 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 prop の変更を処理
• 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 - プロバイダー階層を正しく構成

移行前チェックリスト

移行を開始する前に、特別な処理が必要なパターンについてコードベースをスキャンしてください：

# WebSocket ライブラリを確認 (webpack フォールバック設定が必要)
grep -E "(socket\.io|\"ws\")" package.json

# SCSS :export 構文を確認 (--webpack フラグが必要な場合)
grep -r ":export" --include="*.scss" src/

# SVG ReactComponent インポートを確認 (SVGR 設定が必要)
grep -r "ReactComponent" --include="*.ts" --include="*.tsx" src/

# すべての REACT_APP_ 環境変数をリスト
grep -roh "REACT_APP_[A-Z_]*" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" src/ | sort -u

# Redux extraReducers がオブジェクト記法を使用しているか確認 (RTK v2 では builder パターンに変換が必要)
grep -r "extraReducers:" --include="*.js" --include="*.jsx" --include="*.ts" --include="*.tsx" src/

# /app/ パスを確認 ((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
SVG の ReactComponent インポート	assets-static-imports
REACT_APP_ 変数が見つかった	env-prefix-change
extraReducers: が見つかった	state-redux (RTK v2 builder callback が必要)
ナビゲーション内の /app/ パス	routing-route-groups (route groups のパスを更新)

使い方

詳細な説明とコード例については、個別のルールファイルを読んでください：

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

各ルールファイルに含まれるもの：

• 移行ステップの簡潔な説明
• CRA の「前」コード例
• Next.js の「後」コード例
• 追加のコンテキストと注意点

移行順序

最適な結果を得るには、以下の順序で移行してください：

1. Setup - Next.js プロジェクト構造を初期化
2. Routing - React Router をファイルベースのルーティングに変換
3. Environment Variables - 環境変数プレフィックスを更新
4. Components - 必要に応じて 'use client' ディレクティブを追加
5. Data Fetching - useEffect をサーバーパターンに変換
6. Styling - グローバル CSS を移動、CSS-in-JS を構成
7. Images & Fonts - Next.js の最適化を採用
8. SEO - Metadata API に移行
9. API Routes - Route Handlers を作成
10. Testing - テスト設定を更新

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

移行後、アプリケーションが正しく動作していることを確認してください：

コア機能：

• npm run dev が Next.js dev サーバーをエラーなしで起動
• npm run build が正常に完了
• npm start がプロダクションビルドを実行
• メインアプリケーションが正しくレンダリング
• すべてのルートがアクセス可能

クライアントサイド機能：

• localStorage/sessionStorage の永続化が機能
• ダークモードやテーマトグルが機能して永続化
• クライアントサイドのインタラクティビティ (フォーム、ボタン、モーダル) が機能
• ブラウザの戻る/進むナビゲーションが正しく機能

ルーティング (該当する場合)：

• ハッシュベースのルーティングが機能 (例：#room=abc,key=xyz)
• クエリパラメーターが正しく読み取られる
• ダイナミックルートが正しいパラメーターでレンダリング
• 無効なルートに 404 ページが表示

リアルタイム機能 (該当する場合)：

• WebSocket 接続が正常に確立
• リアルタイムコラボレーションまたは更新が機能
• 切断後の再接続が機能

インテグレーション (該当する場合)：

• エラーモニタリング (Sentry) がエラーをキャプチャ
• アナリティクストラッキングが正しく送信
• サードパーティ認証 (OAuth、Firebase) が機能
• ファイルアップロードが機能

PWA (該当する場合)：

• Service Worker が登録される (プロダクションビルド)
• アプリがインストール可能
• オフライン機能が期待通りに動作

パフォーマンス：

• コンソールに hydration mismatch 警告がない
• 画像が読み込まれて最適化されている
• フォントが FOUT/FOIT の問題なく読み込まれている
• 予期しないコンソールエラーまたは警告がない