Vite からの移行

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

切り替える理由

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

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

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

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

自動コード分割がない

上記の読み込み時間の遅さの問題は、コード分割である程度管理できます。ただし、手動でコード分割を実行しようとすると、パフォーマンスが悪化することがよくあります。手動でコード分割を行うと、意図せずにネットワークウォーターフォールが発生しやすくなります。Next.js は、ルーターに組み込まれた自動コード分割を提供します。

パフォーマンスの低下の一般的な原因は、アプリケーションがデータを取得するために一連のクライアントサーバーリクエストを行う場合です。SPA でのデータフェッチの一般的なパターンの 1 つは、最初にプレースホルダーをレンダリングし、コンポーネントがマウントされた後にデータをフェッチすることです。残念ながら、これは、データをフェッチする子コンポーネントは、親コンポーネントが独自のデータのロードを完了するまでフェッチを開始できないことを意味します。

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

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

React Suspenseによるストリーミングの組み込みサポートにより、ネットワークウォーターフォールを発生させることなく、UIのどの部分を最初に、どの順序でロードするかをより意図的に制御できます。

これにより、ロードが速く、レイアウトシフトを排除したページを構築できます。

データ取得戦略の選択

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

ミドルウェア

Next.jsミドルウェアを使用すると、リクエストが完了する前にサーバーでコードを実行できます。これは特に、認証が必要なページにユーザーがアクセスしたときに、ユーザーをログインページにリダイレクトすることにより、認証されていないコンテンツのフラッシュを回避するのに役立ちます。ミドルウェアは、実験や国際化にも役立ちます。

組み込みの最適化

画像、フォント、およびサードパーティ製スクリプトは、アプリケーションのパフォーマンスに大きな影響を与えることがよくあります。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を使用していない場合は、この手順をスキップできます。

tsconfig.node.jsonへのプロジェクト参照を削除します。
include配列に./dist/types/**/*.tsと./next-env.d.tsを追加します。
exclude配列に./node_modulesを追加します。
compilerOptionsのplugins配列に{ "name": "next" }を追加します: "plugins": [{ "name": "next" }]
esModuleInteropをtrueに設定します: "esModuleInterop": true
jsxをpreserveに設定します: "jsx": "preserve"
allowJsをtrueに設定します: "allowJs": true
forceConsistentCasingInFileNamesをtrueに設定します: "forceConsistentCasingInFileNames": true
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ファイルをルートレイアウトファイルに変換します。

srcディレクトリに新しいappディレクトリを作成します。
そのappディレクトリ内に新しいlayout.tsxファイルを作成します。

app/layout.tsx

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

覚えておくと便利: Layoutファイルには.js、.jsx、または.tsx拡張子が使用できます。

以前に作成した<RootLayout>コンポーネントにindex.htmlファイルの内容をコピーし、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>
  )
}

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>
  )
}

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>
  )
}

最後に、Next.jsはMetadata 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の規約ベースのアプローチ（Metadata API）を使用するようになりました。このアプローチにより、ページのSEOとWeb共有のしやすさをより簡単に向上させることができます。

ステップ 5: エントリーポイントページの作成

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

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

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

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

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
}

覚えておくと便利: Pageファイルには、.js、.jsx、または.tsx拡張子が使用できます。

このファイルは、サーバーコンポーネントです。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'ディレクティブで定義されたクライアントコンポーネントです。クライアントコンポーネントは、クライアントに送信される前にサーバー上で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>コンポーネントに移行して、画像の最適化を利用できます。

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

// Before
import logo from '/logo.png'
 
// After
import logo from '../public/logo.png'

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

// 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環境変数も提供しません。ただし、必要な場合は、構成することができます。

.envファイルに以下を追加します。

.env

# ...
NEXT_PUBLIC_BASE_PATH="/some-base-path"

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

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の利点のほとんどを活用していません。ここから段階的に変更を加えて、すべての利点を享受できます。次に何をすべきかの提案を以下に示します。

React RouterからNext.js App Routerに移行して、以下を手に入れましょう。
- 自動コード分割
- ストリーミングサーバーレンダリング
- React Server Components
<Image>コンポーネントで画像を最適化する
next/fontでフォントを最適化する
<Script>コンポーネントでサードパーティスクリプトを最適化する
Next.jsのルールをサポートするようにESLintの設定を更新する