【実務・中級編】Viteの『Pre-bundling』最適化：依存ライブラリのキャッシュを制御して初回起動のコールドスタートを高速化する – ビルド・パッケージ管理ツール生産性向上バイブル

こんにちは。テックリードの私だ。

日々の開発において、`npm run dev`（あるいは`vite`）を実行した瞬間の「あの数秒のモタつき」、そして大規模なモノレポやサードパーティライブラリを大量に抱えたプロジェクトにおけるコールドスタートの遅さに、イライラした経験はないだろうか。

「Viteは爆速だ」という触れ込みで導入したものの、プロジェクトが肥大化するにつれて初回起動が重くなり、挙句の果てに `node_modules` をいじった途端にモジュール解決がおかしくなり、祈りながら `rm -rf node_modules .vite && npm install` を叩く――。この儀式に、エンジニアとしての貴重な時間を年間で何十時間もドブに捨ててはいないか？

今回は、Viteの心臓部である「依存関係事前構築（Pre-bundling）」のメカニズムを解剖し、そのキャッシュ戦略を完全掌握することで、開発サーバーのコールドスタートを極限まで加速させるプロの実践テクニックを伝授する。

—

1. なぜViteの「Pre-bundling」でコールドスタートが遅くなるのか？

まず、Viteが裏側で何をやっているのかを正確に理解しよう。

Viteは、ブラウザのネイティブESM（ES Modules）を前提とした極めてモダンなビルドツールだ。開発時には、ブラウザからのリクエストに応じて個別のソースコードを都度トランスパイルして返す。しかし、ここには致命的なボトルネックが存在する。

それが 「CommonJS / UMDモジュールの混入」 と 「莫大なモジュールリクエスト数（Waterfal問題）」 だ。

内部で起きていること

1. ESM化の必要性:
ReactやLodashなどのサードパーティライブラリは、依然としてCommonJS（`require` / `module.exports`）形式で配布されているものが多い。ブラウザはこれを直接解釈できない。
2. 依存関係の検出:
Viteは起動時、ソースコードをスキャン（コードホッピング）して `import` されているサードパーティの依存関係（例: `import React from ‘react’`）を自動検出する。
3. esbuildによる事前バンドル:
検出された依存関係を、Go言語製で超高速な bundler である `esbuild` を用いて、一つのESMファイルにまとめ上げる（Pre-bundling）。
4. キャッシュへの保存:
生成されたバンドル品は、プロジェクトルートの `node_modules/.vite`（または設定されたキャッシュディレクトリ）にキャッシュされる。

ボトルネックの正体

初回起動時や、キャッシュが無効化されたタイミングでは、この `esbuild` による事前バンドル処理が走る。依存パッケージが数百個に及び、それらが深くネストしている場合、このスキャンとバンドルに数秒〜十数秒の遅延（コールドスタートの遅延）が発生するのだ。

さらに、Viteはパッケージ内の何百という内部モジュール（例: `lodash-es` の個別関数など）をブラウザが数珠つづきにリクエストするのを防ぐため、これらを1つのファイルに束ねる役割もこの事前バンドルで担っている。ここを制することが、Viteチューニングのすべてと言っても過言ではない。

—

2. キャッシュの仕組みと「効かなくなる」アンチパターン

Viteは、無駄な事前バンドルを避けるために巧妙なキャッシュ機構を持っている。
`node_modules/.vite/deps` 配下に生成されるファイル群と、同じく同ディレクトリ内にある `_metadata.json` がその鍵だ。

キャッシュの無効化（バス）判定のメカニズム

Viteは、以下の情報が変更されたときにキャッシュが無効であると判断し、事前バンドルを再実行する。

1. `package.json` の `dependencies` / `devDependencies` のハッシュ値
2. パッケージマネージャーのロックファイル（`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`）の更新日時（mtime）または内容
3. `vite.config.ts` の設定内容の変更

⚠️ 現場で頻発する「キャッシュがバグる」原因

チーム開発において、以下のような状況に陥ったことはないか？

• `git pull` で他のメンバーのブランチを取り込んだ際、ライブラリのバージョンは変わっていないのに挙動がおかしくなる。
• ワークスペース（Monorepo）環境で、内部パッケージ（workspace packages）のソースコードを書き換えてもViteがそれを検知せず、古いビルド結果を参照し続ける。

これは、Viteのデフォルトのスキャナーが 「`node_modules` 外のローカルパッケージの変更をロックファイルの変更とみなさない」 ケースがあるためだ。結果として、古いキャッシュが残り続け、型エラーやモジュール未解決地獄に突入する。

—

3. プロが実践する `optimizeDeps` 究極のチューニング設定

この問題を根本から解決し、コールドスタートを劇的に高速化するための `vite.config.ts` のベストプラクティスを提示する。

以下の設定は、大規模なプロダクション環境やモノレポで実際に成果を上げている構成だ。

// vite.config.ts
import { defineConfig } from ‘vite’
import react from ‘@vitejs/plugin-react’
import { resolve } from ‘path’

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

// 依存関係事前構築の最適化設定
optimizeDeps: {
// 1. 強制的に事前バンドルさせたい依存関係を指定
// 動的インポート（import()）されていてスキャン漏れしやすいライブラリをここに記述することで、
// 初回アクセス時のオンデマンド・リビルド（ページ再読み込みの発生）を防ぐ。
include: [
‘react’,
‘react-dom’,
‘react-router-dom’,
‘lodash-es’,
‘@mui/material’,
‘@emotion/react’,
‘@emotion/styled’,
],

// 2. 事前バンドルから除外すべき依存関係を指定
// リンクされたローカルパッケージ（Monorepoの子パッケージなど）や、
// 頻繁にHMRの対象として直接コードをいじりたい自己製UIライブラリなどを指定する。
// ここを指定することで、無駄な事前バンドル処理の走査コストを削減できる。
exclude: [
‘@my-company/shared-types’, // 頻繁に書き換えるローカルパッケージ
],

// 3. esbuild自体の挙動をハックする
esbuildOptions: {
// ターゲット環境の指定。古いブラウザを切り捨てるなら最新のESNextを指定してパース速度を上げる
target: ‘esnext’,

// 必要に応じてプラグインを注入し、特定のCommonJSライブラリの変換を強制する
plugins: [
// 例: 特定のレガシーライブラリのグローバル変数をポリフィルする場合など
]
},

// 4. 強制スキャンの有効化（デフォルトは自動だが、依存関係の検出漏れを防ぐために明示することも有効）
// force: true, // ※通常時はビルドが遅くなるためコメントアウト。キャッシュクリア時のみコマンド経由で実行推奨
},

server: {
// 5. ファイルウォッチャーの最適化
// Docker環境やWSL2環境でinotifyの制限に引っかかる場合や、ファイル変更検知を高速化する
watch: {
usePolling: false, // CPU負荷を下げるため極力false。WSL2やDockerでファイル検知しない場合はtrueを検討
interval: 100, // ポーリング間隔のミリ秒
},

// サーバー起動時のポートやホスト設定
port: 3000,
host: true,
},
})

設定の意図とアーキテクチャ上のメリット

• `optimizeDeps.include` の事前定義: Viteは静的解析で `import` 文を辿るため、動的インポート（`await import(…)`）や条件分岐の中にあるライブラリを見落とすことがある。これらをあらかじめ `include` に明示することで、開発サーバー起動時の `esbuild` が一度に正確なバンドルを作成し、ブラウザからの初回リクエスト時の遅延（ページローディングの引っかかり）を完全に排除できる。
• `optimizeDeps.exclude` によるモノレポ対策: モノレポ環境において、自社製の内部パッケージを `exclude` しないと、内部パッケージの些細な修正のたびにViteが依存関係全体の事前バンドルを再計算しようとしてしまう。ここを分離することで、ローカルパッケージは通常のHMR（Hot Module Replacement）の恩恵をダイレクトに受けられるようになる。

—

4. チーム開発を加速させる「共有化ルール」と自動化スクリプト

個人がローカルで `rm -rf node_modules/.vite` を手動で叩く運用は、属人化を産むため今すぐ廃止すべきだ。チーム全体でキャッシュの整合性を保ち、トラブルシューティングをワンコマンド化するための仕組みを導入する。

1. package.json に「クリーン＆スタート」スクリプトを定義する

開発者が迷ったときに実行する共通の合言葉として、明示的なクリーンアップコマンドを定義しておく。

// package.json
{
“scripts”: {
“dev”: “vite”,
// 依存関係キャッシュとViteの事前ビルドキャッシュを綺麗に掃除して起動する神コマンド
“dev:clean”: “rimraf node_modules/.vite && vite –force”,
// node_modulesも含めて完全リセットしてクリーンインストールする最終防衛ライン
“reset:all”: “rimraf node_modules package-lock.json node_modules/.vite && npm install && npm run dev”
}
}

(※ `rimraf` はクロスプラットフォームで安全にディレクトリを削除できるため、開発メンバーがWindowsであれmacOSであれ確実に動作する)

2. Git Hooks (Husky + lint-staged) によるロックファイル監視

`package.json` が更新されたにもかかわらず、うっかり `npm install` を忘れてビルドエラーになる事故を防ぐため、`post-merge` または `post-checkout` フックで自動的にViteキャッシュを無効化するスクリプトを仕込むのがプロの現場だ。

`.git/hooks/post-merge` （または Husky等で管理）に以下を配置する。

!/bin/sh
依存関係が変更されたコミットをマージした際、自動的にViteのキャッシュをクリアする
changed_files=”$(git diff-tree -r –name-only –no-commit-id ORIG_HEAD HEAD)”

check_file() {
echo “$changed_files” | grep -q “$1”
}

if check_file “package.json” || check_file “package-lock.json” || check_file “pnpm-lock.yaml”; then
echo “📦 依存関係の変更を検知しました。Viteの事前ビルドキャッシュをクリアします…”
rm -rf node_modules/.vite
fi

これにより、メンバーは「なぜか動かない」という不毛なトラブルから解放される。

—

5. 開発スピードを極限まで引き上げる「神プラグイン」

最後に、Viteのコールドスタートや依存関係の管理をさらに一段上のレベルへ引き上げる、インフラストラクチャ寄りの神プラグインを二つ紹介する。

1. `vite-plugin-inspect`

• 用途: Viteの内部パイプライン、プラグインフックの処理時間、各モジュールの変換前後のコードをブラウザ上で視覚的にインスペクトするツール。
• なぜ必要か: 「どのプラグインがビルドを重くしているのか」「事前バンドルされたモジュールがどのように解決されているのか」をブラックボックスのままにせず、可視化してボトルネックを数値で殴り殺すために使う。

// vite.config.ts への導入例
import Inspect from ‘vite-plugin-inspect’

export default defineConfig({
plugins: [
Inspect(), // 開発サーバー起動中、 http://localhost:3000/__inspect/ で内部状態を完全覗き見できる
],
})

2. `vite-plugin-compression` (または `vite-plugin-compression2`)

• 用途: ビルド時にアセットを自動で Gzip / Brotli 圧縮する。
• なぜ実務で効くのか: 本番環境やステージング環境へのデプロイ前段階におけるプレビュー検証（`vite preview`）の起動速度や、巨大な事前バンドルチャンクの転送効率を最適化し、実機検証のフィードバックループを高速化する。

—

6. まとめ：アーキテクトからのメッセージ

ViteのPre-bundlingは、正しく飼い慣らせば強力な開発の翼となるが、仕組みを理解せずに放置すれば、チーム全体の生産性をジワジワと蝕む隠れた負債となる。

今回解説した内容は、単なる「設定のコピペ」ではない。

• 「なぜキャッシュが無効化されるのか」というデータ構造の理解
• `optimizeDeps` による依存関係の意図的なコントロール
• チーム全体でキャッシュ不整合を自動化で防ぐ仕組み作り

これらをあなたのプロジェクトに落とし込むことで、チームのエンジニア全員が「モタつき」から解放され、コードを書くことに純粋に集中できる極上の開発環境が手に入るはずだ。

明日からのビルド速度の変化を、ぜひその肌で感じてみてほしい。