コンテンツにスキップ
ガイド移行Vite

ViteからNext.jsへの移行方法

このガイドは、既存のViteアプリケーションをNext.jsに移行するのに役立ちます。

なぜ切り替えるのか？

ViteからNext.jsに切り替えたい理由はいくつかあります。

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

React 用の デフォルトの Vite プラグイン でアプリケーションを構築した場合、そのアプリケーションは純粋なクライアントサイドアプリケーションです。シングルページアプリケーション（SPA）としても知られるクライアントサイドのみのアプリケーションでは、初期ページ読み込み時間が遅くなることがよくあります。これはいくつかの理由によります。

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

自動コード分割がない

前述の読み込み時間の遅延問題は、コード分割である程度管理できます。しかし、手動でコード分割を試みると、パフォーマンスが悪化することがよくあります。手動でのコード分割では、誤ってネットワークウォーターフォールを導入してしまうことがあります。Next.js はルーターに組み込まれた自動コード分割を提供します。

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

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

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

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

React Suspense によるストリーミングの組み込みサポートにより、ネットワークウォーターフォールを導入することなく、UI のどの部分を最初に、どの順序で読み込むかについて、より意図的に設定できます。

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

データ取得戦略を選択する

ニーズに応じて、Next.js ではページおよびコンポーネントごとにデータ取得戦略を選択できます。ビルド時、サーバーでのリクエスト時、またはクライアントでの取得を選択できます。たとえば、CMS からデータを取得し、ビルド時にブログ投稿をレンダリングして、CDN で効率的にキャッシュすることができます。

プロキシ

Next.js Proxy は、リクエストが完了する前にサーバーでコードを実行できるようにします。これは、認証が必要なページにユーザーがアクセスした際に、ログインページにリダイレクトすることで、認証されていないコンテンツの一瞬の表示を防ぐのに特に役立ちます。プロキシは、実験や国際化にも役立ちます。

組み込みの最適化

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

移行手順

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

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

まず、next を依存関係としてインストールする必要があります。

ターミナル
npm install next@latest

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

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

next.config.mjs
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export', // Outputs a Single-Page Application (SPA).
  distDir: './dist', // Changes the build output directory to `./dist/`.
}
 
export default nextConfig

重要: Next.js の設定ファイルには .js または .mjs のいずれかを使用できます。

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

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

  1. tsconfig.node.json へのプロジェクト参照を削除します。
  2. tsconfig.json の include 配列に ./dist/types/**/*.ts と ./next-env.d.ts を追加します。
  3. tsconfig.json の exclude 配列に ./node_modules を追加します。
  4. compilerOptions の plugins 配列 に { "name": "next" } を追加します: "plugins": [{ "name": "next" }]
  5. esModuleInterop を true に設定します: esModuleInterop: "esModuleInterop": true
  6. jsx を react-jsx に設定します: jsx: "jsx": "react-jsx"
  7. allowJs を true に設定します: allowJs: "allowJs": true
  8. forceConsistentCasingInFileNames を true に設定します: forceConsistentCasingInFileNames: "forceConsistentCasingInFileNames": true
  9. incremental を true に設定します: incremental: "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": "react-jsx",
    "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 ファイルを作成します。
app/layout.tsx
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return '...'
}

重要: レイアウトファイルには .js、.jsx、または .tsx の拡張子を使用できます。

  1. index.html ファイルの内容を、前述の <RootLayout> コンポーネントにコピーし、body.div#root と body.script タグを <div id="root">{children}</div> に置き換えます。
app/layout.tsx
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>
  )
}
  1. Next.js には、meta charset と meta viewport タグがデフォルトで含まれているため、<head> から安全に削除できます。
app/layout.tsx
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>
  )
}
  1. favicon.ico、icon.png、robots.txt などの メタデータファイルは、app ディレクトリの最上位に配置されている限り、アプリケーションの <head> タグに自動的に追加されます。サポートされているすべてのファイルを app ディレクトリに移動した後、それらの <link> タグを安全に削除できます。
app/layout.tsx
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>
  )
}
  1. 最後に、Next.js は メタデータ API を使用して、最後の <head> タグを管理できます。最終的なメタデータ情報をエクスポートされた metadata オブジェクトに移動します。
app/layout.tsx
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>
  )
}

上記変更により、index.html ですべてを宣言するのではなく、フレームワークに組み込まれた Next.js の規約ベースのアプローチ（メタデータ API）を使用するようになりました。このアプローチにより、ページの SEO と Web での共有可能性をより簡単に向上させることができます。

ステップ 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 ファイルを作成し、以下の内容を記述します。
app/[[...slug]]/page.tsx
import '../../index.css'
 
export function generateStaticParams() {
  return [{ slug: [''] }]
}
 
export default function Page() {
  return '...' // We'll update this
}

重要: ページファイルには .js、.jsx、または .tsx の拡張子を使用できます。

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

このファイルはグローバル CSS をインポートし、generateStaticParams に、ルート / のルートを 1 つだけ生成することを伝えます。

次に、クライアント専用で実行される Vite アプリケーションの残りの部分を移動します。

app/[[...slug]]/client.tsx
'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 です。Client Components は、クライアントに送信される前にサーバーで HTML に事前レンダリングされます。

開始時にクライアント専用アプリケーションを希望するため、App コンポーネント以下では事前レンダリングを無効にするように Next.js を設定できます。

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

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

app/[[...slug]]/page.tsx
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` will be '/assets/img.2d8efhg.png' in production
 
export default function App() {
  return <img src={image} />
}

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

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

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

  1. /public からインポートした画像の絶対インポートパスを相対インポートに変換します。
// Before
import logo from '/logo.png'
 
// After
import logo from '../public/logo.png'
  1. <img> タグに画像オブジェクト全体ではなく、画像 src プロパティを渡します。
// Before
<img src={logo} />
 
// After
<img src={logo.src} />

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

警告: TypeScript を使用している場合、src プロパティにアクセスする際に型エラーが発生する可能性があります。このガイドの終了まで、それらを安全に無視できます。

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

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

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

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

  • 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', // Outputs a Single-Page Application (SPA).
  distDir: './dist', // Changes the build output directory to `./dist/`.
  basePath: process.env.NEXT_PUBLIC_BASE_PATH, // Sets the base path to `/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 を実行し、https://: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 のメリットのほとんどを活用できていませんが、段階的な変更を加えて、すべてのメリットを享受することができます。次に何をすべきか: