Create React App から Next.js への移行方法

このガイドでは、既存の Create React App (CRA) サイトを Next.js に移行する方法を説明します。

なぜ移行するのか？

Create React App から Next.js に移行したい理由はいくつかあります：

初期ページ読み込み時間の遅さ

Create React App は純粋にクライアントサイドの React を使用しています。クライアントサイドのみのアプリケーション、別名シングルページアプリケーション (SPA) は、初期ページ読み込み時間が遅くなることがよくあります。これは以下の理由によります：

ブラウザは、React コードとアプリケーション全体のバンドルがダウンロードされて実行されるまで待つ必要があります。
新しい機能や依存関係を追加するたびにアプリケーションコードが増加します。

自動コード分割がない

前述の読み込み時間の遅さの問題は、コード分割である程度緩和できます。しかし、手動でコード分割を試みると、ネットワークウォーターフォールを引き起こす可能性があります。Next.js は、自動コード分割と tree-shaking をルーターとビルドパイプラインに組み込んでいます。

ネットワークウォーターフォール

パフォーマンスが悪化する一般的な原因は、データを取得するためにクライアントとサーバー間で順次リクエストを行うことです。SPA でのデータ取得のパターンの1つは、プレースホルダーをレンダリングし、コンポーネントがマウントされた後にデータを取得することです。残念ながら、子コンポーネントは親が自身のデータを読み込んだ後でしかデータを取得できないため、リクエストの「ウォーターフォール」が発生します。

Next.js ではクライアントサイドのデータ取得もサポートされていますが、データ取得をサーバーに移動することもできます。これにより、クライアントとサーバー間のウォーターフォールが完全に排除されることがよくあります。

高速で意図的な読み込み状態

React Suspense を通じたストリーミングの組み込みサポートにより、ネットワークウォーターフォールを作成せずに、UI のどの部分を最初にどの順序で読み込むかを定義できます。

これにより、ページの読み込みが速くなり、レイアウトシフトを排除できます。

データ取得戦略の選択

必要に応じて、Next.js ではページまたはコンポーネントレベルでデータ取得戦略を選択できます。たとえば、CMS からデータを取得し、ビルド時（SSG）にブログ投稿をレンダリングして高速な読み込み速度を実現したり、必要に応じてリクエスト時（SSR）にデータを取得したりできます。

ミドルウェア

Next.js ミドルウェアを使用すると、リクエストが完了する前にサーバー上でコードを実行できます。たとえば、認証が必要なページのミドルウェアでユーザーをログインページにリダイレクトすることで、未認証コンテンツのフラッシュを回避できます。また、A/B テスト、実験、国際化などの機能にも使用できます。

組み込みの最適化

画像、フォント、およびサードパーティスクリプトは、アプリケーションのパフォーマンスに大きな影響を与えることがよくあります。Next.js には、これらを自動的に最適化するための専用コンポーネントと API が含まれています。

移行手順

私たちの目標は、できるだけ早く動作する Next.js アプリケーションを作成し、その後で Next.js の機能を段階的に採用できるようにすることです。まず、アプリケーションを純粋なクライアントサイドアプリケーション（SPA）として扱い、既存のルーターをすぐに置き換えないようにします。これにより、複雑さとマージの競合が軽減されます。

注意: package.json のカスタム homepage フィールド、カスタムサービスワーカー、特定の Babel/webpack 調整など、CRA の高度な設定を使用している場合は、Next.js でこれらの機能を再現または適応するためのヒントについて、このガイドの最後にある 追加の考慮事項 セクションを参照してください。

ステップ 1: Next.js の依存関係をインストールする

既存のプロジェクトに Next.js をインストールします：

Terminal

npm install next@latest

ステップ 2: Next.js の設定ファイルを作成する

プロジェクトの root に next.config.ts を作成します（package.json と同じレベル）。このファイルには、Next.js の設定オプションが含まれます。

next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  output: 'export', // シングルページアプリケーション (SPA) を出力します
  distDir: 'build', // ビルド出力ディレクトリを `build` に変更します
}

export default nextConfig

注意: output: 'export' を使用すると、静的エクスポートを行っていることを意味します。サーバーサイドの機能（SSR や API など）にはアクセスできません。Next.js のサーバー機能を活用するには、この行を削除できます。

ステップ 3: Root レイアウトを作成する

Next.js App Router アプリケーションには、すべてのページをラップする root レイアウトファイルが必要です。これは、React Server Component です。

CRA アプリケーションでの root レイアウトファイルに最も近いものは、<html>、<head>、および <body> タグを含む public/index.html です。

src ディレクトリ内に新しい app ディレクトリを作成します（または、app を root に配置する場合はプロジェクトの root に作成します）。
app ディレクトリ内に layout.tsx（または layout.js）ファイルを作成します：

TypeScript
JavaScript

app/layout.tsx
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return '...'
}

app/layout.js
export default function RootLayout({ children }) {
  return '...'
}

古い index.html の内容をこの <RootLayout> コンポーネントにコピーします。body div#root（および body noscript）を <div id="root">{children}</div> に置き換えます。

TypeScript
JavaScript

app/layout.tsx
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <head>
        <meta charSet="UTF-8" />
        <link rel="icon" href="%PUBLIC_URL%/favicon.ico" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <title>React App</title>
        <meta name="description" content="Web site created..." />
      </head>
      <body>
        <div id="root">{children}</div>
      </body>
    </html>
  )
}

app/layout.js
export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <head>
        <meta charset="UTF-8" />
        <link rel="icon" href="%PUBLIC_URL%/favicon.ico" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <title>React App</title>
        <meta name="description" content="Web site created..." />
      </head>
      <body>
        <div id="root">{children}</div>
      </body>
    </html>
  )
}

Good to know: Next.js はデフォルトで CRA の public/manifest.json、追加のアイコン、およびテスト設定を無視します。これらが必要な場合、Next.js は Metadata API とテストのセットアップをサポートしています。

ステップ 4: メタデータ

Next.js は <meta charset="UTF-8" /> と <meta name="viewport" content="width=device-width, initial-scale=1" /> タグを自動的に含めるため、<head> から削除できます：

TypeScript
JavaScript

app/layout.tsx
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <head>
        <link rel="icon" href="%PUBLIC_URL%/favicon.ico" />
        <title>React App</title>
        <meta name="description" content="Web site created..." />
      </head>
      <body>
        <div id="root">{children}</div>
      </body>
    </html>
  )
}

app/layout.js
export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <head>
        <link rel="icon" href="%PUBLIC_URL%/favicon.ico" />
        <title>React App</title>
        <meta name="description" content="Web site created..." />
      </head>
      <body>
        <div id="root">{children}</div>
      </body>
    </html>
  )
}

favicon.ico、icon.png、robots.txt などのメタデータファイルは、app ディレクトリのトップレベルに配置されている限り、アプリケーションの <head> タグに自動的に追加されます。すべてのサポートされているファイルを app ディレクトリに移動した後、それらの <link> タグを安全に削除できます：

TypeScript
JavaScript

app/layout.tsx
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <head>
        <title>React App</title>
        <meta name="description" content="Web site created..." />
      </head>
      <body>
        <div id="root">{children}</div>
      </body>
    </html>
  )
}

app/layout.js
export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <head>
        <title>React App</title>
        <meta name="description" content="Web site created..." />
      </head>
      <body>
        <div id="root">{children}</div>
      </body>
    </html>
  )
}

最後に、Next.js は Metadata API を使用して最後の <head> タグを管理できます。最終的なメタデータ情報をエクスポートされた metadata オブジェクトに移動します：

TypeScript
JavaScript

app/layout.tsx
import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: 'React App',
  description: 'Web site created with Next.js.',
}

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <div id="root">{children}</div>
      </body>
    </html>
  )
}

app/layout.js
export const metadata = {
  title: 'React App',
  description: 'Web site created with Next.js.',
}

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <div id="root">{children}</div>
      </body>
    </html>
  )
}

上記の変更により、index.html にすべてを宣言する方法から、フレームワークに組み込まれた Next.js の規約ベースのアプローチ（Metadata API）を使用する方法に移行しました。このアプローチにより、ページの SEO とウェブの共有性をより簡単に向上させることができます。

ステップ 5: スタイル

CRA と同様に、Next.js は CSS Modules を標準でサポートしています。また、グローバル CSS インポートもサポートしています。

グローバル CSS ファイルがある場合は、app/layout.tsx にインポートします：

TypeScript

app/layout.tsx
import '../index.css'

export const metadata = {
  title: 'React App',
  description: 'Web site created with Next.js.',
}

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <div id="root">{children}</div>
      </body>
    </html>
  )
}

Tailwind CSS を使用している場合は、インストールドキュメントを参照してください。

ステップ 6: エントリーポイントページを作成する

Create React App は src/index.tsx（または index.js）をエントリーポイントとして使用します。Next.js（App Router）では、app ディレクトリ内の各フォルダがルートに対応し、各フォルダには page.tsx が必要です。

現在のところアプリを SPA として保持し、すべてのルートをインターセプトしたいので、optional catch-all route を使用します。

app 内に [[...slug]] ディレクトリを作成します。

app
 ┣ [[...slug]]
 ┃ ┗ page.tsx
 ┣ layout.tsx

page.tsx に次の内容を追加します：

TypeScript
JavaScript

app/[[...slug]]/page.tsx
export function generateStaticParams() {
  return [{ slug: [''] }]
}

export default function Page() {
  return '...' // 後で更新します
}

app/[[...slug]]/page.js
export function generateStaticParams() {
  return [{ slug: [''] }]
}

export default function Page() {
  return '...' // 後で更新します
}

これは Next.js に空のスラッグ（/）のための単一のルートを生成するよう指示し、すべてのルートを同じページにマッピングします。このページはServer Componentであり、静的 HTML にプリレンダリングされます。

ステップ 7: クライアント専用のエントリーポイントを追加する

次に、CRA の root App コンポーネントをClient Component内に埋め込み、すべてのロジックをクライアントサイドに残します。Next.js を初めて使用する場合、クライアントコンポーネント（デフォルトでは）もサーバーでプリレンダリングされることを知っておく価値があります。クライアントサイドの JavaScript を実行する追加の機能を持っていると考えることができます。

app/[[...slug]]/ に client.tsx（または client.js）を作成します：

TypeScript
JavaScript

app/[[...slug]]/client.tsx
'use client'

import dynamic from 'next/dynamic'

const App = dynamic(() => import('../../App'), { ssr: false })

export function ClientOnly() {
  return <App />
}

app/[[...slug]]/client.js
'use client'

import dynamic from 'next/dynamic'

const App = dynamic(() => import('../../App'), { ssr: false })

export function ClientOnly() {
  return <App />
}

'use client' ディレクティブは、このファイルをクライアントコンポーネントにします。
dynamic インポートと ssr: false は <App /> コンポーネントのサーバーサイドレンダリングを無効にし、真にクライアント専用（SPA）にします。

次に、page.tsx（または page.js）を更新して新しいコンポーネントを使用します：

TypeScript
JavaScript

app/[[...slug]]/page.tsx
import { ClientOnly } from './client'

export function generateStaticParams() {
  return [{ slug: [''] }]
}

export default function Page() {
  return <ClientOnly />
}

app/[[...slug]]/page.js
import { ClientOnly } from './client'

export function generateStaticParams() {
  return [{ slug: [''] }]
}

export default function Page() {
  return <ClientOnly />
}

ステップ 8: 静的画像インポートを更新する

CRA では、画像ファイルをインポートすると、その公開 URL が文字列として返されます：

import image from './img.png'

export default function App() {
  return <img src={image} />
}

Next.js では、静的画像インポートはオブジェクトを返します。このオブジェクトは Next.js の <Image> コンポーネントで直接使用することができ、または既存の <img> タグでオブジェクトの src プロパティを使用することができます。

<Image> コンポーネントには自動画像最適化の追加の利点があります。<Image> コンポーネントは、画像の寸法に基づいて結果の <img> の width と height 属性を自動的に設定します。これにより、画像が読み込まれるときのレイアウトシフトを防ぎます。ただし、アプリに寸法の一方のみがスタイルされ、他方が auto にスタイルされていない画像が含まれている場合、問題が発生する可能性があります。auto にスタイルされていない場合、寸法は <img> の寸法属性の値にデフォルト設定され、画像が歪んで表示される可能性があります。

<img> タグを保持することで、アプリケーションの変更量を減らし、上記の問題を防ぐことができます。その後、ローダーを設定するか、画像を自動的に最適化するデフォルトの Next.js サーバーに移行することで、画像を最適化するために <Image> コンポーネントに移行することができます。

/public からインポートされた画像の絶対インポートパスを相対インポートに変換します：

// 変更前
import logo from '/logo.png'

// 変更後
import logo from '../public/logo.png'

画像オブジェクト全体ではなく、画像の src プロパティを <img> タグに渡します：

// 変更前
<img src={logo} />

// 変更後
<img src={logo.src} />

または、ファイル名に基づいて画像アセットの公開 URL を参照することもできます。たとえば、public/logo.png はアプリケーションの /logo.png で画像を提供し、これが src 値になります。

警告: TypeScript を使用している場合、src プロパティにアクセスするときに型エラーが発生する可能性があります。これを修正するには、tsconfig.json ファイルの include 配列に next-env.d.ts を追加する必要があります。Next.js は、ステップ 9 でアプリケーションを実行するときにこのファイルを自動的に生成します。

ステップ 9: 環境変数を移行する

Next.js は CRA と同様に環境変数をサポートしていますが、ブラウザで公開したい変数には NEXT_PUBLIC_ プレフィックスが必要です。

主な違いは、クライアントサイドで環境変数を公開するために使用されるプレフィックスです。REACT_APP_ プレフィックスを持つすべての環境変数を NEXT_PUBLIC_ に変更します。

ステップ 10: `package.json` のスクリプトを更新する

package.json のスクリプトを Next.js コマンドに更新します。また、.next と next-env.d.ts を .gitignore に追加します：

package.json
{
  "scripts": {
    "dev": "next dev --turbopack",
    "build": "next build",
    "start": "npx serve@latest ./build"
  }
}

.gitignore
# ... \{#}
.next
next-env.d.ts

次のコマンドを実行できます：

npm run dev

http://localhost:3000 を開きます。Next.js（SPA モード）でアプリケーションが実行されているのが確認できるはずです。

ステップ 11: クリーンアップ

Create React App に特有のアーティファクトを削除できます：

public/index.html
src/index.tsx
src/react-app-env.d.ts
reportWebVitals のセットアップ
react-scripts の依存関係（package.json からアンインストール）

追加の考慮事項

CRA でカスタム `homepage` を使用する

CRA の package.json で homepage フィールドを使用してアプリを特定のサブパスで提供していた場合、Next.js の next.config.ts で basePath 設定を使用してそれを再現できます：

next.config.ts
import { NextConfig } from 'next'

const nextConfig: NextConfig = {
  basePath: '/my-subpath',
  // ...
}

export default nextConfig

カスタム `Service Worker` の処理

CRA のサービスワーカー（例：create-react-app の serviceWorker.js）を使用していた場合、Next.js でプログレッシブウェブアプリケーション (PWA)を作成する方法を学ぶことができます。

API リクエストのプロキシ

CRA アプリで package.json の proxy フィールドを使用してバックエンドサーバーへのリクエストを転送していた場合、next.config.ts で Next.js のリライトを使用してこれを再現できます：

next.config.ts
import { NextConfig } from 'next'

const nextConfig: NextConfig = {
  async rewrites() {
    return [
      {
        source: '/api/:path*',
        destination: 'https://your-backend.com/:path*',
      },
    ]
  },
}

カスタム Webpack / Babel 設定

CRA でカスタム webpack または Babel 設定を持っていた場合、next.config.ts で Next.js の設定を拡張できます：

next.config.ts
import { NextConfig } from 'next'

const nextConfig: NextConfig = {
  webpack: (config, { isServer }) => {
    // ここで webpack 設定を変更します
    return config
  },
}

export default nextConfig

注意: これには dev スクリプトから --turbopack を削除して Turbopack を無効にする必要があります。

TypeScript のセットアップ

Next.js は tsconfig.json がある場合、自動的に TypeScript をセットアップします。tsconfig.json の include 配列に next-env.d.ts がリストされていることを確認してください：

{
  "include": ["next-env.d.ts", "app/**/*", "src/**/*"]
}

バンドラーの互換性

Create React App と Next.js はどちらもデフォルトで webpack をバンドリングに使用します。Next.js はまた、ローカル開発をより高速にするための Turbopack を提供しています：

next dev --turbopack

CRA から高度な webpack 設定を移行する必要がある場合は、カスタム webpack 設定を提供することもできます。

次のステップ

すべてが正常に動作した場合、現在はシングルページアプリケーションとして動作する Next.js アプリケーションがあります。まだサーバーサイドレンダリングやファイルベースのルーティングなどの Next.js の機能を活用していませんが、これらを段階的に行うことができます：

Next.js App Router にReact Router から移行して：
- 自動コード分割
- ストリーミングサーバーレンダリング
- React Server Components
<Image> コンポーネントで画像を最適化
next/fontでフォントを最適化
<Script> コンポーネントでサードパーティスクリプトを最適化
npx next lint を実行し、プロジェクトのニーズに合わせて設定することで、Next.js 推奨ルールでESLint を有効化

注意: 静的エクスポート（output: 'export'）を使用すると、useParams フックやその他のサーバー機能が現在サポートされていません。すべての Next.js 機能を使用するには、next.config.ts から output: 'export' を削除してください。

なぜ移行するのか？​

初期ページ読み込み時間の遅さ​

自動コード分割がない​

ネットワークウォーターフォール​

高速で意図的な読み込み状態​

データ取得戦略の選択​

ミドルウェア​

組み込みの最適化​

移行手順​

ステップ 1: Next.js の依存関係をインストールする​

ステップ 2: Next.js の設定ファイルを作成する​

ステップ 3: Root レイアウトを作成する​

ステップ 4: メタデータ​

ステップ 5: スタイル​

ステップ 6: エントリーポイントページを作成する​

ステップ 7: クライアント専用のエントリーポイントを追加する​

ステップ 8: 静的画像インポートを更新する​

ステップ 9: 環境変数を移行する​

ステップ 10: package.json のスクリプトを更新する​

ステップ 11: クリーンアップ​

追加の考慮事項​

CRA でカスタム homepage を使用する​

カスタム Service Worker の処理​

API リクエストのプロキシ​

カスタム Webpack / Babel 設定​

TypeScript のセットアップ​

バンドラーの互換性​

次のステップ​