Vite: フロントエンド開発サーバーとビルド ツール

Vite は、最新のフロントエンド プロジェクトで一般的に使用される開発サーバーおよびビルド ツールです。

React + TypeScript + Vite プロジェクトでは、主に次のことを担当します。

1. 開発ステージ: 開発サーバーを起動し、高速なモジュールのロードとホット モジュールの交換を提供します (HMR)。
2. 本番ビルド ステージ: TypeScript、JSX、CSS およびその他のソース コードを、ブラウザーが読み込める静的リソースに変換、最適化、パッケージ化します。

全体的なプロセス:

React / TypeScript Source
           │
           ▼
          Vite
           │
     ┌─────┴─────┐
     ▼           ▼
Development   Production
     │           │
 Dev Server    Build
     │           │
     ▼           ▼
 HMR / ESM     dist/
                 │
                 ▼
           Nginx / CDN
                 │
                 ▼
              Browser

プレーンな React SPA と同様に、Vite は運用サーバー上で継続的に実行する必要はありません。構築された HTML、JavaScript、CSS およびその他のリソースは、Nginx から直接提供できます。

1.開発サーバー(Dev Server)

開始コマンド

pnpm dev

通常は package.json に対応します。

{
  "scripts": {
    "dev": "vite"
  }
}

通常、デフォルトの開発アドレスは次のとおりです。

http://localhost:5173

一般的なコマンド:

# 開発サーバーを起動します
pnpm dev

# ポートの指定
pnpm dev -- --port 3000

# LANまたはコンテナ外へのアクセスを許可する
pnpm dev -- --host 0.0.0.0

# ビルド前の依存関係を強制的に再ビルドする
pnpm dev -- --force

pnpm dev -- の -- は、実行のために後続のパラメータをスクリプトに渡すプログラムを表します。

開発サーバーの仕組み

従来の Bundler では通常、開発サービスを提供する前に一部またはすべてのモジュールを構築する必要があります。

Vite は、ブラウザのネイティブ ES Modules (ESM) を使用して、オンデマンドでソース コード モジュールを変換して提供します。

Browser
   │
   ├── GET /src/main.tsx
   │
   ├── GET /src/App.tsx
   │
   └── GET /src/components/Header.tsx
                  │
                  ▼
             Vite Dev Server
                  │
                  ▼
           Transform / Serve

これにより、大規模なプロジェクトの開始時に実行する必要がある作業量が削減されます。

ただし、Vite は開発段階でモジュール変換と依存関係の事前構築を実行し、構築処理をまったく実行しません。

2. HMR（Hot Module Replacement）

HMR は、Vite 開発経験の中核となるメカニズムの 1 つです。

ソースコードが変更されると、次のようになります。

Modify React Component
          ↓
Vite Detects Changes
          ↓
HMR Update
          ↓
Browser Replaces Module
          ↓
Page Updates

HMR ページ全体を再読み込みするのではなく、変更されたモジュールのみを更新することができます。

React Fast Refresh

React プロジェクトは通常、以下を使用します。

import react from "@vitejs/plugin-react";

React Fast Refresh は HMR に基づいており、条件が満たされたときにコンポーネントを更新し、可能な場合は React State を保持します。

たとえば、次のように変更します。

export function Counter() {
  const [count, setCount] = useState(0);

  return <button>{count}</button>;
}

コンポーネント コードが変更された後、場合によってはカウンターの状態を保持できることがあります。

注:

• HMR は、ユニバーサル モジュールのホット交換メカニズムです。
• Fast Refresh は、React コンポーネント専用のホット アップデート メカニズムです。
• Fast Refresh コンポーネントのステータスが変更のたびに保持されるという保証はありません。

3. 依存関係の事前構築 (Dependency Pre-Bundling)

Vite 開発段階では通常、いくつかのサードパーティの依存関係が前処理されます。

たとえば:

import React from "react";
import axios from "axios";

これらの依存関係には次のものが関係する場合があります。

• CommonJSからESM。
• 内部モジュールが豊富。
• マルチレベルの依存関係参照。

Vite は、依存関係の最適化メカニズムを使用して、事前に構築された適切な依存関係を変換およびマージし、開発段階での読み込み効率を向上させます。

キャッシュは通常、次の場所にあります。

node_modules/.vite/

optimizeDeps

設定可能:

export default defineConfig({
  optimizeDeps: {
    include: ["react", "react-dom"],
    exclude: [],
  },
});

通常、optimizeDeps を手動で変更する必要はありません。

特定の依存関係の読み込みが遅い、CommonJS の互換性の問題、または異常な依存関係の検出が発生した場合にのみ、調整する価値があります。

は事前構築に依存します。これは主に開発環境の最適化メカニズムであり、運用環境の Code Splitting と同等ではありません。

4. 製品版ビルド (Production Build)

実行:

pnpm build

通常、以下に対応します。

{
  "scripts": {
    "build": "tsc -b && vite build"
  }
}

実行プロセス:

TypeScript Type Check
          ↓
       Vite Build
          ↓
    Module Bundling
          ↓
     Tree Shaking
          ↓
      Minification
          ↓
       dist/

注: vite build 自体が主に構築を担当し、tsc --noEmit のように TypeScript の完全なセマンティック型チェックを実行しません。

したがって、React + TypeScript プロジェクトは通常単独で実行されます。

tsc -b

製品を構築する

通常、次のものが生成されます。

dist/
├── index.html
└── assets/
    ├── index-A1b2C3.js
    ├── index-D4e5F6.css
    ├── MapPage-K7m8N9.js
    └── logo-P1q2R3.svg

これらのファイルは、Nginx または CDN にデプロイされた静的リソースです。

build構成

export default defineConfig({
  build: {
    outDir: "dist",
    sourcemap: false,
    emptyOutDir: true,
    chunkSizeWarningLimit: 500,
  },
});

chunkSizeWarningLimit は警告しきい値を制御するだけで、実際に Bundle サイズを減らすことはありません。

5. Preview: 実稼働ビルドのプレビュー

pnpm build
pnpm preview

通常、以下に対応します。

{
  "scripts": {
    "preview": "vite preview"
  }
}

機能:

dist/
  ↓
Vite Preview Server
  ↓
Browser

以下のチェックに使用できます。

• 構築後のページが正常かどうか。
• 動的インポートは正しいですか?
• 静的リソース パスが有効かどうか。
• ページルートにアクセスできるかどうか。

vite preview は主にローカル プレビューに使用され、公式運用サーバーとしては推奨されません。

6. vite.config.ts

Vite の主な構成ファイルは通常次のとおりです。

vite.config.ts

React + TypeScript + Tailwind CSS プロジェクトの例:

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
  plugins: [react(), tailwindcss()],

  server: {
    host: "127.0.0.1",
    port: 5173,

    proxy: {
      "/api": {
        target: "http://localhost:8000",
        changeOrigin: true,
      },
    },
  },

  build: {
    outDir: "dist",
    sourcemap: false,
  },

  resolve: {
    tsconfigPaths: true,
  },

  base: "/",
});

ここでの resolve.tsconfigPaths は、このオプションをサポートする Vite の新しいバージョンに適用されます。古いバージョンでは引き続き resolve.alias を使用できます。

共通の構成カテゴリ

7. パスのエイリアス (Alias)

コード構造を仮定すると、次のようになります。

src/
├── components/
│   └── Button.tsx
├── pages/
└── main.tsx

Alias を使用しない場合:

import { Button } from "../../components/Button";

Alias を使用します。

import { Button } from "@/components/Button";

TypeScript構成

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Vite構成

方法 1: resolve.alias を使用します。

import { fileURLToPath, URL } from "node:url";

export default defineConfig({
  resolve: {
    alias: {
      "@": fileURLToPath(new URL("./src", import.meta.url)),
    },
  },
});

方法 2: 新しいバージョン Vite を使用できます。

resolve: {
  tsconfigPaths: true,
}

Vite が、一致する tsconfig.json に基づいてパス エイリアスを解決します。

注: この機能は解析のオーバーヘッドを引き起こす可能性があり、CSS またはサードパーティ ツールでのパス解析の問題をすべて解決できるわけではありません。

8. 開発エージェント (server.proxy)

開発中、React と Django は異なるポートで実行される場合があります。

React → localhost:5173
Django → localhost:8000

設定可能:

server: {
  proxy: {
    "/api": {
      target: "http://localhost:8000",
      changeOrigin: true,
    },
  },
},

ブラウザリクエスト:

GET http://localhost:5173/api/v1/pois/

Vite はリクエストを次の宛先に転送します。

GET http://localhost:8000/api/v1/pois/

このようにして、フロントエンド コードで相対アドレスを使用できるようになります。

axios.get("/api/v1/pois/");

開発環境で直接別の Origin をリクエストする必要はありません。

本番環境

server.proxy は、Vite 開発サーバーでのみ使用されます。

通常、Nginx は制作を担当します。

Browser
   ↓
Nginx
   ├── /assets/ → Static Files
   ├── /api/    → Django
   └── /        → React SPA

9. 環境変数(Environment Variables)

Vite は、.env ファイルを使用して、さまざまな環境の構成を管理します。

共通の文書:

.env
.env.local
.env.development
.env.production
.env.staging

例

.env.development：

VITE_API_URL=http://localhost:8000

.env.production：

VITE_API_URL=https://api.example.com

コードは次のようになります:

const apiUrl = import.meta.env.VITE_API_URL;

組み込みの環境変数

たとえば:

if (import.meta.env.DEV) {
  console.log("Development");
}

一部の開発固有のコードは、静的置換と Tree Shaking を使用して実稼働ビルド中に削除できます。

環境変数のセキュリティ

デフォルトでは、VITE_ プレフィックスが付いたカスタム環境変数のみがクライアント コードに公開されます。

ただし、特別な注意が必要です。

ブラウザに公開されるすべての環境変数は公開情報とみなされます。

入れられないもの:

• データベースのパスワード。
• Django SECRET_KEY。
• プライベートAPI Token。
• サーバーのアクセス認証情報。

Build-time および Runtime

Vite のクライアント環境変数は通常、ビルド時に決定されます。

.env.production
       ↓
    vite build
       ↓
  JavaScript Bundle
       ↓
    Nginx

ビルド後にサーバー上の .env.production を変更しても、既に生成されている JS ファイルは自動的に変更されません。

実行時の動的な構成が必要な場合は、追加の構成ファイルまたは構成インターフェイス メカニズムが必要です。

10. 静的リソースの処理

Vite 静的リソース管理には主に 2 つの方法があります。

src/assets

src/assets/logo.png

使用:

import logo from "@/assets/logo.png";

function Logo() {
  return <img src={logo} alt="Logo" />;
}

Vite ビルド時にリソース パスを処理し、リソースの内容、サイズ、構成に基づいてインライン化またはハッシュ ファイルを生成する場合があります。

たとえば:

/assets/logo-Cx7Ab91.png

public

public/favicon.ico

通常は変更せずに次の場所にコピーされます。

dist/favicon.ico

使用:

<img src="/favicon.ico" alt="Favicon" />

両者の違い

共通のアプリケーション画像、フォント、その他のリソースは通常、src/assets の最初に配置されます。

固定ファイル名または固定 URL を維持する必要があるリソースは、public に配置できます。

11. Code Splitting (コード分割)

Code Splitting は、ユーザーが最初にアクセスしたときにアプリケーション コード全体をダウンロードする必要がないように、JavaScript を複数の Chunk に分割するために使用されます。

Dynamic Import

import { lazy, Suspense } from "react";

const MapPage = lazy(() => import("./pages/MapPage"));

function App() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <MapPage />
    </Suspense>
  );
}

Vite は、実稼働ビルド中に動的にインポートされたモジュールを独立した Chunk に分割できます。

たとえば:

dist/assets/
├── index-A1b2.js
├── MapPage-C3d4.js
└── maplibre-E5f6.js

実際の分割結果は、モジュールの依存関係とビルド構成によって異なります。

Lazy Loading および Code Splitting

この 2 つは関連していますが、同一ではありません。

• Code Splitting: コードを個別にロードできる複数のファイルに分割します。
• Lazy Loading: 必要になるまでコードまたはリソースの読み込みを延期します。

一般的なプロセス:

User Opens Homepage
         ↓
      main.js
         ↓
User Opens Map Page
         ↓
   MapPage Chunk
         ↓
  MapLibre Chunk

MapPage がホームページ上ですぐにレンダリングされる場合、lazy() が使用されている場合でも、関連モジュールがホームページ上に読み込まれる可能性があります。

真のページレベルの遅延読み込みは、ルーティングまたは条件付きレンダリングと調整する必要があります。

12. Tree Shaking

Tree Shaking は、ビルド プロセス中に使用されないと判断されたコードを削除するために使用されます。

たとえば:

export function a() {}
export function b() {}
export function c() {}

引用してみましょう:

import { a } from "./utils";

Vite は、静的解析と副作用処理の条件が満たされた場合、運用ビルドで未使用の b() と c() を削除できます。

制限事項

Tree Shaking は次の要因の影響を受ける可能性があります。

• CommonJS。
• 動的参照。
• モジュールの副作用。
• サードパーティは梱包方法に依存しています。
• ビルダーはコードが使用されていないことを証明できません。

したがって、ES Modules を使用すると、ビルド ツールによる静的解析の実行には役立ちますが、未使用のコードがすべて削除されることは保証されません。

13. Minification (コード圧縮)

通常、実稼働ビルドは JavaScript と CSS を圧縮します。

ソースコードの例:

function calculateTotal(price: number, quantity: number) {
  return price * quantity;
}

圧縮後は次のようになります。

function t(n, r) {
  return n * r;
}

Minification には主に次のものが含まれます。

• 不要な空白やコメントを削除します。
• ローカル識別子を短縮します。
• 表現を簡略化します。
• 役に立たないことが判明したコードを削除します。

Minification および gzip/Brotli

これらはさまざまな問題を解決します。

一般的なプロセス:

Source Code
     ↓
Vite Minification
     ↓
Minified JavaScript
     ↓
Nginx Brotli / gzip
     ↓
Network Transfer
     ↓
Browser Decompression
     ↓
Parse / Compile / Execute

gzip/Brotli は、解凍後にブラウザーが処理する必要がある JavaScript コードの量を削減しません。

14. Bundleの分析と最適化

MapLibre のように依存ボリュームが大きい場合でもビルドプロダクトを解析できます。

一般的な最適化手法

1. ページ レベル Lazy Loading を使用します。
2. エントリ ファイルに大きな依存関係を直接導入することは避けてください。
3. Dynamic Importを使用してください。
4. Tree Shakingを利用してください。
5. Chunkを合理的に分割します。
6. HTTP 圧縮とキャッシュを有効にします。

manualChunks

一部の Vite バージョンと基礎となるビルダーは、手動の下請け構成をサポートしています。次に例を示します。

build: {
  rollupOptions: {
    output: {
      manualChunks: {
        map: ["maplibre-gl"],
      },
    },
  },
},

注: これは、従来の Rollup 構成に基づく例です。新しいバージョン Vite API では、基になるビルダーと対応する構成が異なる場合があるため、使用する場合はバージョンの互換性を確認する必要があります。

さらに、Chunk を手動で分割しても、必ずしも合計コード サイズが削減されるわけではありません。また、関連する Chunk が最初の画面に読み込まれないことも保証されません。

一般に、最初に動的インポートとデフォルトのコード分割戦略を使用し、Bundle を分析した後でのみ Chunk を手動で調整することをお勧めします。

ビルドボリュームの警告

Some chunks are larger than 500 kB

これは、一部の Chunk 値がより大きいというビルド ツールからの通知です。これは、ビルドが失敗したという意味でも、ページに重大なパフォーマンスの問題があるはずという意味でもありません。

次のことも考慮する必要があります。

• 圧縮後のネットワークのサイズ。
• 最初の画面リソースに属するかどうか。
• 長期間キャッシュするかどうか。
• JavaScript 解析と実行のオーバーヘッド。
• 実際のデバイスのパフォーマンス。

15. Source Map

製品コードは Minification を通過することが多いため、エラー スタックを読み取るのは簡単ではない可能性があります。

たとえば:

function a(e) {
  return e + 1;
}

Source Map は、ビルドされたコードの場所を元のソース コードにマッピングするのに役立ちます。

Production Error
       ↓
Minified JS Position
       ↓
Source Map
       ↓
src/components/Map.tsx:32

構成:

build: {
  sourcemap: true,
},

共通オプション

Sentry などのエラー監視サービスの場合は、hidden の使用と Source Map のアップロードを検討してください。

注: Source Map はソース コード構造を公開する可能性があるため、直接公開するのには適さない可能性があります。

16. Base: デプロイメントのベースパス

base は、アプリケーションがパブリックにアクセスできる場合に、リソースのベース パスを構成するために使用されます。

ルートパスにデプロイする

https://example.com/

構成:

base: "/",

サブパスにデプロイする

https://example.com/my-app/

構成:

base: "/my-app/",

Vite は、base を調整して構築されています。

• JS リソース参照。
• CSS リソース参照。
• 静的リソースのパス。
• HTML の関連リソースのアドレス。

注: base は React Router を自動的に構成しません。

React Router が Browser History を使用し、サブパスの下にデプロイされている場合、Router の basename も正しく構成する必要があります。

17. Plugin: Vite プラグインシステム

Vite はプラグインを通じて機能を拡張します。

一般的なプラグイン:

たとえば:

export default defineConfig({
  plugins: [react(), tailwindcss()],
});

Vite のプラグイン メカニズムは Rollup プラグイン システムと互換性がありますが、Vite は開発サーバーとモジュール変換のための独自の機能も提供します。

18. Vite および Nginx の本番展開

Vite は静的リソースの構築を担当し、Nginx は運用環境での HTTP サービスを担当します。

React Source
     ↓
  Vite Build
     ↓
    dist/
     ↓
Docker Image
     ↓
   Nginx
     ↓
  Browser

Docker マルチステージビルド

# Stage 1: Build
FROM node:24-alpine AS build

WORKDIR /app

COPY package.json pnpm-lock.yaml ./

RUN corepack enable && pnpm install --frozen-lockfile

COPY . .

RUN pnpm build

# Stage 2: Serve
FROM nginx:alpine

COPY --from=build /app/dist /usr/share/nginx/html

COPY nginx.conf /etc/nginx/conf.d/default.conf

この方法では、最終的な実行イメージに Node.js 開発依存関係を含める必要がありません。

Nginx SPA構成

server {
    listen 80;

    root /usr/share/nginx/html;
    index index.html;

    location /assets/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    location / {
        try_files $uri $uri/ /index.html;
    }

    location = /index.html {
        add_header Cache-Control "no-cache";
    }
}

ここでは、Vite がデフォルトで /assets/ を使用してハッシュ付きの静的リソースを出力すると仮定します。

index.html を長期間キャッシュできないのはなぜですか?

Vite ビルド ファイルには通常、コンテンツ ハッシュが含まれています。

index-A1b2C3.js

コード更新後:

index-X9y8Z7.js

したがって、ハッシュされたファイルは長期間キャッシュされる可能性があります。

ただし、index.html は新しい JS/CSS ファイルを参照する責任があるため、最新のビルドをタイムリーに検出できなければなりません。

推奨:

index.html
    ↓
no-cache（使用前に再確認してください）

assets/*.js
assets/*.css
    ↓
Long-term Cache

注: SPA の場合は、存在しない静的リソースが誤って index.html にフォールバックしないようにする必要もあります。そうしないと、JavaScript MIME Type エラーが発生する可能性があります。

19. Vite、Nginx、およびブラウザの責任

一般的な生産の最適化:

React.lazy()
      ↓
Dynamic Import
      ↓
Vite Code Splitting
      ↓
Hashed Static Assets
      ↓
Nginx gzip / Brotli
      ↓
Cache-Control
      ↓
Browser

これは、React SPA の一般的な運用展開方法です。

20. Vite よくある質問

Q1: Vite Web Framework ですか?

いいえ。

Vite は主に開発サーバーとビルド ツールです。

React は UI を担当します。 React Router はクライアント ルーティングを担当します。 Viteが開発と構築を担当しています。

Q2: Vite 運用環境では Node.js を実行する必要がありますか?

通常の静的React SPAの場合は不要です。

Vite ビルドによって生成された静的リソースは、Nginx または CDN によって直接提供できます。

ただし、SSR などのサーバー側レンダリング シナリオでは、Node.js またはその他のサーバー ランタイムが必要になる場合があります。

Q3: Vite は自動的に gzip をオンにしますか?

運用サーバーは gzip に対して自動的に有効になりません。

ビルド出力に表示される gzip ボリュームは通常、単なる圧縮されたボリューム情報であり、gzip が有効になった Nginx を表すものではありません。

Q4: Vite の後に Code Splitting が自動的に続くことはできますか?

できる。

Vite のプロダクション ビルダーは、モジュールの関係や動的インポートなどの情報に基づいて Chunk を生成します。

ただし、実際の分割結果は、ビルダー、プラグイン、構成の影響を受けます。

Q5: Vite と Webpack の違いは何ですか?

どちらもフロントエンドのビルドを完了できます。

Vite の主な機能は、ネイティブ ESM を活用して迅速な開発サービスを提供し、プロダクション ビルダーを使用して出力リソースを最適化することです。

Webpack は、高度に構成可能なモジュール パッケージ化メカニズムを提供します。

2 つの実際のパフォーマンスは、使用するプロジェクトのサイズ、構成、バージョンによって異なります。 1 つのツールがすべての状況で高速であると単純に考えることはできません。

概要

Vite の核となる知識は 4 つの部分に分けることができます。

React + TypeScript SPA プロジェクトの場合、習得すべき最も重要なことは次のとおりです。

1. 開発サーバーが HMR でどのように動作するか。
2. vite.config.tsの共通構成。
3. 開発プロキシと運用リバース プロキシの違い。
4. 環境変数のビルド時の挿入メカニズム。
5. Dynamic ImportとCode Splitting。
6. 静的リソース Hash とブラウザー キャッシュ。
7. Vite Build と TypeScript のタイプ チェックの違い。

---

参考資料

• Vite Official Documentation
• Vite Features
• Vite Configuration
• Vite Build
• Environment Variables and Modes
• Static Asset Handling