logoNext.js 日本語
ドキュメントブログ学習
はじめに/アプリケーションの構築/アップグレード/Vite からの移行

Vite からの移行

このガイドでは、既存の Vite アプリケーションを Next.js に移行する方法を説明します。

移行する理由

Vite から Next.js に切り替えるべき理由はいくつかあります:

初期ページ読み込みが遅い

Vite のデフォルト React プラグインを使ってアプリケーションを構築した場合、それは純粋なクライアントサイドアプリケーションです。クライアントサイドのみのアプリケーション（シングルページアプリケーション、SPA）は、初期ページの読み込みが遅くなる傾向があります。これには以下の理由があります:

  1. ブラウザは、データ読み込みリクエストを送信する前に、React コードとアプリケーション全体のバンドルがダウンロードされ実行されるのを待つ必要がある
  2. 新しい機能や依存関係を追加するたびにアプリケーションコードが肥大化する

自動コード分割の欠如

読み込み時間の遅さはコード分割である程度改善できますが、手動でコード分割を実施するとパフォーマンスが悪化する可能性があります。手動でのコード分割では、ネットワークのウォーターフォール現象を引き起こしやすいです。Next.js にはルーターに組み込まれた自動コード分割機能があります。

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

パフォーマンス低下の一般的な原因は、アプリケーションがデータ取得のためにクライアント-サーバー間で順次リクエストを行う場合です。SPA でのデータ取得の一般的なパターンは、最初にプレースホルダーをレンダリングし、コンポーネントがマウントされた後にデータを取得するものです。残念ながら、これはデータを取得する子コンポーネントが、親コンポーネントが自身のデータの読み込みを完了するまで待たなければならないことを意味します。

Next.js ではクライアント側でのデータ取得がサポートされていますが、サーバー側にデータ取得を移行するオプションも提供されており、クライアント-サーバー間のウォーターフォールを排除できます。

高速で意図的なローディング状態

React Suspense を使ったストリーミングの組み込みサポートにより、UI のどの部分をどの順序で最初に読み込むかを意図的に制御でき、ネットワークウォーターフォールを導入せずに済みます。

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

データ取得戦略の選択

Next.js では、ページやコンポーネントごとにデータ取得戦略を選択できます。ビルド時、サーバーでのリクエスト時、クライアント側での取得などが可能です。例えば、CMS からデータを取得してブログ記事をビルド時にレンダリングし、CDN で効率的にキャッシュできます。

ミドルウェア

Next.js ミドルウェアを使用すると、リクエストが完了する前にサーバー上でコードを実行できます。これは、認証が必要なページにユーザーがアクセスした際に未認証コンテンツが一瞬表示されるのを防ぎ、ログインページにリダイレクトする場合などに特に有用です。また、実験や国際化にも役立ちます。

組み込み最適化

画像、フォント、サードパーティスクリプトはアプリケーションのパフォーマンスに大きな影響を与えます。Next.js にはこれらを自動的に最適化する組み込みコンポーネントが含まれています。

移行手順

この移行の目標は、できるだけ早く動作する Next.js アプリケーションを取得し、その後段階的に Next.js の機能を採用できるようにすることです。最初は、既存のルーターを移行せずに純粋なクライアントサイドアプリケーション（SPA）として維持します。これにより、移行プロセス中に問題が発生する可能性を最小限に抑え、マージコンフリクトを減らせます。

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

最初に next を依存関係としてインストールします:

Terminal
npm install next@latest

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

プロジェクトのルートに next.config.mjs を作成します。このファイルにはNext.js の設定オプションが含まれます。

next.config.mjs
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export', // シングルページアプリケーション（SPA）として出力
  distDir: './dist', // ビルド出力ディレクトリを `./dist/` に変更
}

export default nextConfig

豆知識: Next.js 設定ファイルには .js または .mjs が使用できます。

ステップ 3: TypeScript 設定の更新

TypeScript を使用している場合、Next.js と互換性を持たせるために tsconfig.json ファイルを以下のように更新します。TypeScript を使用していない場合はこのステップをスキップできます。

  1. tsconfig.node.json へのプロジェクト参照を削除
  2. include 配列に ./dist/types/**/*.ts と ./next-env.d.ts を追加
  3. exclude 配列に ./node_modules を追加
  4. compilerOptions の plugins 配列に { "name": "next" } を追加: "plugins": [{ "name": "next" }]
  5. esModuleInterop を true に設定: "esModuleInterop": true
  6. jsx を preserve に設定: "jsx": "preserve"
  7. allowJs を true に設定: "allowJs": true
  8. forceConsistentCasingInFileNames を true に設定: "forceConsistentCasingInFileNames": true
  9. incremental を true に設定: "incremental": true

以下はこれらの変更を加えた動作する tsconfig.json の例です:

tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "useDefineForClassFields": true,
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "preserve",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "allowJs": true,
    "forceConsistentCasingInFileNames": true,
    "incremental": true,
    "plugins": [{ "name": "next" }]
  },
  "include": ["./src", "./dist/types/**/*.ts", "./next-env.d.ts"],
  "exclude": ["./node_modules"]
}

TypeScript の設定についての詳細は Next.js ドキュメントで確認できます。

ステップ 4: ルートレイアウトの作成

Next.js のApp Router アプリケーションには、アプリケーション内のすべてのページをラップするReact Server Component であるルートレイアウトファイルが必要です。このファイルは app ディレクトリの最上位レベルで定義されます。

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

このステップでは、index.html ファイルをルートレイアウトファイルに変換します:

  1. src ディレクトリ内に新しい app ディレクトリを作成
  2. その app ディレクトリ内に新しい layout.tsx ファイルを作成:
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return null
}
export default function RootLayout({ children }) {
  return null
}

豆知識: レイアウトファイルには .js、.jsx、.tsx 拡張子が使用可能

  1. index.html ファイルの内容を先ほど作成した <RootLayout> コンポーネントにコピーし、body.div#root と body.script タグを <div id="root">{children}</div> に置き換えます:
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <head>
        <meta charset="UTF-8" />
        <link rel="icon" type="image/svg+xml" href="/icon.svg" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>My App</title>
        <meta name="description" content="My App is a..." />
      </head>
      <body>
        <div id="root">{children}</div>
      </body>
    </html>
  )
}
export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <head>
        <meta charset="UTF-8" />
        <link rel="icon" type="image/svg+xml" href="/icon.svg" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>My App</title>
        <meta name="description" content="My App is a..." />
      </head>
      <body>
        <div id="root">{children}</div>
      </body>
    </html>
  )
}
  1. Next.js にはデフォルトでmeta charset とmeta viewport タグが含まれているので、<head> からこれらを安全に削除できます:
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <head>
        <link rel="icon" type="image/svg+xml" href="/icon.svg" />
        <title>My App</title>
        <meta name="description" content="My App is a..." />
      </head>
      <body>
        <div id="root">{children}</div>
      </body>
    </html>
  )
}
export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <head>
        <link rel="icon" type="image/svg+xml" href="/icon.svg" />
        <title>My App</title>
        <meta name="description" content="My App is a..." />
      </head>
      <body>
        <div id="root">{children}</div>
      </body>
    </html>
  )
}
  1. favicon.ico、icon.png、robots.txt などのメタデータファイルは、app ディレクトリの最上位に配置されていれば自動的にアプリケーションの <head> タグに追加されます。サポートされているファイルをすべて app ディレクトリに移動した後、それらの <link> タグを安全に削除できます:
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <head>
        <title>My App</title>
        <meta name="description" content="My App is a..." />
      </head>
      <body>
        <div id="root">{children}</div>
      </body>
    </html>
  )
}
export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <head>
        <title>My App</title>
        <meta name="description" content="My App is a..." />
      </head>
      <body>
        <div id="root">{children}</div>
      </body>
    </html>
  )
}
  1. 最後に、Next.js はMetadata API を使って最後の <head> タグを管理できます。最終的なメタデータ情報をエクスポートされたmetadata オブジェクトに移動します:
import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: 'My App',
  description: 'My App is a...',
}

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <div id="root">{children}</div>
      </body>
    </html>
  )
}
export const metadata = {
  title: 'My App',
  description: 'My App is a...',
}

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: エントリーポイントページの作成

Next.jsでは、page.tsxファイルを作成することでアプリケーションのエントリーポイントを宣言します。Viteにおけるmain.tsxファイルに相当するものです。このステップでは、アプリケーションのエントリーポイントを設定します。

  1. appディレクトリ内に[[...slug]]ディレクトリを作成

このガイドではまずNext.jsをSPA（シングルページアプリケーション）として設定することを目指しているため、アプリケーションのすべてのルートをキャッチするページエントリーポイントが必要です。そのために、appディレクトリ内に新しい[[...slug]]ディレクトリを作成してください。

このディレクトリはオプショナルキャッチオールルートセグメントと呼ばれるものです。Next.jsはファイルシステムベースのルーターを使用しており、ディレクトリを使ってルートを定義します。この特別なディレクトリにより、アプリケーションのすべてのルートが含まれるpage.tsxファイルに誘導されます。

  1. app/[[...slug]]ディレクトリ内に新しいpage.tsxファイルを作成し、以下の内容を記述:
import '../../index.css'

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

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

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

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

補足: ページファイルには.js、.jsx、.tsxの拡張子が使用できます。

このファイルはサーバーコンポーネント (Server Component)です。next buildを実行すると、このファイルは静的アセットにプリレンダリングされます。動的なコードは必要ありません。

このファイルはグローバルCSSをインポートし、generateStaticParamsに対して/のインデックスルートのみを生成するように指示しています。

次に、クライアント側でのみ実行されるViteアプリケーションの残りを移動させましょう。

'use client'

import React from 'react'
import dynamic from 'next/dynamic'

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

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

import React from 'react'
import dynamic from 'next/dynamic'

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

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

このファイルは'use client'ディレクティブで定義されたクライアントコンポーネント (Client Component)です。クライアントコンポーネントは、クライアントに送信される前にサーバー側でHTMLにプリレンダリングされます。

最初はクライアントのみのアプリケーションにしたいので、Appコンポーネント以下のプリレンダリングを無効にするようにNext.jsを設定できます。

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

次に、エントリーポイントページを更新して新しいコンポーネントを使用します:

import '../../index.css'
import { ClientOnly } from './client'

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

export default function Page() {
  return <ClientOnly />
}
import '../../index.css'
import { ClientOnly } from './client'

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

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

ステップ6: 静的画像インポートの更新

Next.jsは静的画像のインポートをViteとは少し異なる方法で処理します。Viteでは画像ファイルをインポートすると、その公開URLが文字列として返されます:

App.tsx
import image from './img.png' // 本番環境では`image`は'/assets/img.2d8efhg.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>タグを維持することで、アプリケーションの変更量を減らし、上記の問題を防ぐことができます。その後、必要に応じてローダーを設定して<Image>コンポーネントに移行するか、自動画像最適化が組み込まれたデフォルトのNext.jsサーバーに移行することで、画像を最適化できます。

  1. /publicからインポートされた画像の絶対パスインポートを相対パスに変換:
// 変更前
import logo from '/logo.png'

// 変更後
import logo from '../public/logo.png'
  1. 画像オブジェクト全体ではなくsrcプロパティを<img>タグに渡す:
// 変更前
<img src={logo} />

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

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

警告: TypeScriptを使用している場合、srcプロパティにアクセスすると型エラーが発生する可能性があります。今のところはこれらのエラーを無視しても問題ありません。このガイドの最後までに修正されます。

ステップ7: 環境変数の移行

Next.jsはViteと同様に.env環境変数をサポートしています。主な違いは、クライアント側で環境変数を公開するために使用されるプレフィックスです。

  • VITE_プレフィックスを持つすべての環境変数をNEXT_PUBLIC_に変更してください。

Viteは特別なimport.meta.envオブジェクト上でいくつかの組み込み環境変数を公開していますが、これらはNext.jsではサポートされていません。以下のように使用法を更新する必要があります:

  • import.meta.env.MODE ⇒ process.env.NODE_ENV
  • import.meta.env.PROD ⇒ process.env.NODE_ENV === 'production'
  • import.meta.env.DEV ⇒ process.env.NODE_ENV !== 'production'
  • import.meta.env.SSR ⇒ typeof window !== 'undefined'

Next.jsも組み込みのBASE_URL環境変数を提供していません。ただし、必要に応じて設定することは可能です:

  1. .envファイルに以下を追加:
.env
# ...
NEXT_PUBLIC_BASE_PATH="/some-base-path"
  1. next.config.mjsファイルでbasePathをprocess.env.NEXT_PUBLIC_BASE_PATHに設定:
next.config.mjs
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export', // シングルページアプリケーション(SPA)を出力
  distDir: './dist', // ビルド出力ディレクトリを`./dist/`に変更
  basePath: process.env.NEXT_PUBLIC_BASE_PATH, // ベースパスを`/some-base-path`に設定
}

export default nextConfig
  1. import.meta.env.BASE_URLの使用箇所をprocess.env.NEXT_PUBLIC_BASE_PATHに更新

ステップ8: package.jsonのスクリプトを更新

Next.jsへの移行が成功したかどうかをテストするために、アプリケーションを実行できるようになるはずです。ただし、その前に、package.jsonのscriptsをNext.js関連のコマンドで更新し、.nextとnext-env.d.tsを.gitignoreに追加する必要があります:

package.json
{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}
.gitignore
# ...
.next
next-env.d.ts
dist

npm run devを実行し、http://localhost:3000を開いてください。Next.jsで動作するアプリケーションが表示されるはずです。

例: ViteアプリケーションをNext.jsに移行した実際の例はこのプルリクエストで確認できます。

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

Vite関連のアーティファクトをコードベースから削除できます:

  • main.tsxを削除
  • index.htmlを削除
  • vite-env.d.tsを削除
  • tsconfig.node.jsonを削除
  • vite.config.tsを削除
  • Viteの依存関係をアンインストール

次のステップ

すべてが計画通りに進んだ場合、シングルページアプリケーションとして動作するNext.jsアプリケーションができています。ただし、まだNext.jsの利点のほとんどを活用していませんが、段階的な変更を加えてすべての利点を得ることができます。次に取り組むべきことは以下の通りです:

バージョン14

Next.js アプリケーションをバージョン13から14にアップグレードする方法

Create React App からの移行

既存の React アプリケーションを Create React App から Next.js に移行する方法を学びます。