web-tooling-vite

Vite のパターン

クイックガイド： Vite は開発時にはバンドルされていない ES モジュールを配信し、本番用にはバンドルするため、設定に関する判断の大半はどちらか一方にのみ適用されます。API はバージョンによって決まります。Vite 8 は Rolldown（build.rolldownOptions、codeSplitting.groups、resolve.tsconfigPaths）でバンドルし、Vite 7 は Rollup（build.rollupOptions、manualChunks、手動で tsconfig.json にも反映するエイリアス）を使用します。Sass は Vite 6 以降でモダン API を使用し、レガシー API は Vite 7 で廃止されています。

詳細なリソース：

• examples/core.md — エイリアス、チャンク分割、環境別ビルド、モジュールプリロード、Sass、Environment API、開発プロキシの完全な設定例
• reference.md — 開発／本番設定、ビルドターゲットの表、バージョンごとの注意事項、Vite 8 への移行チェックリスト

---

どのパスを適用するか

設定を書く前に、package.json の vite のバージョンを確認してください。2 つの分岐は名前を共有していますが、動作は異なります。

• Vite 8（Rolldown） — build.rolldownOptions、チャンク分割には codeSplitting.groups、手動でエイリアスを反映する代わりに resolve.tsconfigPaths を使用します。build.rollupOptions も非推奨のエイリアスとして引き続き解決されるため、バージョンに合わない設定でも動作しているように見えます。
• Vite 7（Rollup） — manualChunks と組み合わせて build.rollupOptions を使用し、エイリアスを vite.config.ts と tsconfig.json の両方に宣言します。

---

<critical_requirements>

Vite の設定を書く前に

パスエイリアスはバージョンごとに 1 か所で宣言してください。 Vite 8 では resolve.tsconfigPaths を使用します。Vite 7 では、同じ設定を vite.config.ts と tsconfig.json の両方に記述します。2 つの設定がずれていると、一方のツールでは解決できても他方では解決できず、同じインポートについてビルドとエディターの動作が食い違います。

バンドラーのオプションをバージョンに合わせてください。 Vite 8 では codeSplitting.groups を指定した build.rolldownOptions を使用します。オブジェクト形式の manualChunks はそこで削除されており、チャンク分割が行われなくても何も通知されません。

ビルドを 1 つだけ出荷するのではなく、モードごとに設定を分けてください。 defineConfig(({ mode }) => …) と loadEnv を使えば、開発環境ではミニファイとソースマップを無効にし、本番バンドルにはそれらを含められます。

現在の表記である build.modulePreload.polyfill を使用してください。 build.polyfillModulePreload は非推奨であり、プリロードする依存関係を制御できません。

</critical_requirements>

---

自動検出： Vite、vite.config.ts、vite.config.js、defineConfig、loadEnv、manualChunks、advancedChunks、codeSplitting.groups、rolldownOptions、rollupOptions、modulePreload、resolve.alias、resolve.tsconfigPaths、build.target、baseline-widely-available、VITE_

対象：

• フロントエンドアプリケーションの Vite ビルド設定
• パスエイリアスと、バンドラーおよび型チェッカーの両方で解決可能な状態の維持
• キャッシュ可能な本番出力のためのベンダーチャンク分割
• loadEnv と define を使ったモード別ビルド（開発、ステージング、本番）
• 設定の Vite 7 から Vite 8 への移行
• モジュールプリロード、ビルドターゲット、Sass の前処理

対象外：

• エイリアスに必要な paths エントリー以外のコンパイラーオプションと型チェックの動作
• Lint とフォーマットの設定
• ブラウザーで実行されるアプリケーションコード — ここで扱うのはビルド時の設定のみです
• 独自の設定ファイルを管理する SSR メタフレームワークによるビルドのオーケストレーション
• ビルドコマンドに関するパイプラインとデプロイの問題

---

開発環境と本番環境では、異なる仕組みが動作します。開発サーバーは必要に応じてモジュールを変換し、バンドルせずに配信するため、そこでツリーシェイク、ミニファイ、チャンク分割は行われません。本番ビルドでは、バンドラーがその 3 つすべてを実行します。リリースまで残る不具合はすべて、この差の中にあります。ツリーシェイクで削除されるスタイルシート、本番でしか存在しないチャンク、ローカルでは設定されていた環境変数などです。

そのため、各オプションについて考えるうえで有用な問いは、どちらの環境を対象としているか、そしてもう一方の環境でそのオプションが使われることはあるのか、ということです。

---

<decision_framework>

チャンク分割

Vite 8 (Rolldown)?
├─ Separating vendors by package → codeSplitting.groups with a test regex ✓
└─ Constraining by size or share count → codeSplitting maxSize / minSize / minShareCount

Vite 7 (Rollup)?
├─ Separating vendors by package → manualChunks, object form ✓
└─ Logic per module id → manualChunks, function form

advancedChunks は rolldown-vite での同じ機能名です。Vite 8 では codeSplitting になりました。

ビルドターゲット

Are there browsers below the default floor to support?
├─ YES → @vitejs/plugin-legacy alongside the modern build
└─ NO  → Smallest possible output?
    ├─ YES → 'esnext'
    └─ NO  → 'baseline-widely-available' (the default) ✓, or an explicit list
              such as ['chrome111', 'safari16.4'] when a contract names versions

</decision_framework>

---

基本パターン

パターン 1：パスエイリアス

バンドラーと型チェッカーの両方で解決できる、単一のエイリアスセットです。

// Vite 8 — read straight from tsconfig.json
resolve: { tsconfigPaths: true },

// Vite 7 — declared here and mirrored in tsconfig.json "paths"
resolve: {
  alias: { "@": path.resolve(__dirname, "./src") },
},

resolve.tsconfigPaths は、tsconfig を通じた解決に起動時間がかかるため、デフォルトでは無効です。プロジェクトで paths を使用している場合にのみ有効にしてください。tsconfig.json で宣言された内容のみが対象となるため、paths のエントリーがないエイリアス（プロジェクト外のパッケージや、ビルド用に差し替えられたスタブなど）は、別途 resolve.alias にも指定する必要があります。

コード全文：examples/core.md

---

パターン 2：ベンダーチャンクの分割

依存関係の変更頻度はアプリケーションコードより低いため、チャンクを分けると、デプロイ後もブラウザーキャッシュに保持されます。

// Vite 8
build: {
  rolldownOptions: {
    output: {
      codeSplitting: {
        groups: [{ name: "vendor", test: /[\\/]node_modules[\\/]/ }],
      },
    },
  },
},

依存関係ごとに更新頻度が異なる場合は、グループごとに test を絞り込んでください。すべてをまとめた単一のチャンクでは、どれかをアップグレードするたびに無効になります。

Vite 7 形式を含むコード全文：examples/core.md

---

パターン 3：モード別ビルド

defineConfig は関数を受け取るため、--mode ごとに設定を変えられます。

export default defineConfig(({ mode }) => ({
  build: {
    sourcemap: mode !== "production",
    minify: mode === "production",
  },
}));

.env ファイルの選択は NODE_ENV ではなく、--mode に従います。loadEnv(mode, cwd, "") は、クライアント向けのプレフィックスがないものも含め、すべての変数を返すため、その結果は define に渡すものではなく、サーバー側の値として扱ってください。

コード全文：examples/core.md

---

パターン 4：モジュールプリロード

build: {
  modulePreload: {
    polyfill: false,
    resolveDependencies: (filename, deps) =>
      deps.filter((dep) => !dep.includes("rarely-used-vendor")),
  },
},

ポリフィルを削除しても安全なのは、ターゲットの最低要件がモジュールプリロードをネイティブにサポートしている場合のみです。resolveDependencies を使うと、大きなチャンクを初期プリロードリストから除外できます。

コード全文：examples/core.md

---

パターン 5：Sass

css: {
  preprocessorOptions: {
    scss: {
      additionalData: `@use "./src/styles/variables" as *;`,
    },
  },
},

モダン API は Vite 6 からデフォルトになり、Vite 7 からは唯一の API になりました。そのため、api: "legacy" を指定したままの設定はフォールバックせず、エラーになります。移行では、@import を @use／@forward に置き換え、名前空間を使ってアクセスします。

---

パターン 6：開発サーバーのプロキシ

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

プロキシを使うと開発環境が同一オリジンになるため、本番環境でも同一オリジンとなるバックエンドに対して CORS を設定する必要はありません。

---

パターン 7：環境 API

フレームワークの作成者やマルチランタイムビルド向けです。Vite 8 時点ではまだ RC であり、一般的な単一クライアントアプリには必要ありません。

environments: {
  client: { build: { outDir: "dist/client" } },
  ssr: { build: { outDir: "dist/server", ssr: true } },
},

コード全文：examples/core.md

---

<red_flags>

注意すべき点

実行時に問題が発生します：

• Vite 8 でのオブジェクト形式の manualChunks — 削除されているため、グループ分けが行われず、期待したベンダーチャンクが dist に生成されません
• Vite 7 で削除された splitVendorChunkPlugin — ビルド開始前にインポート時のエラーが発生します
• Vite 7 で削除された target: 'modules' — 'baseline-widely-available' に置き換えられています
• Vite 7 以降での Sass api: "legacy" — レガシー API は非推奨ではなく、廃止されています
• vite.config.ts にエイリアスがあり tsconfig.json にはない場合、またはその逆の場合 — ビルドは成功しても型チェックに失敗するか、エディターでは解決できるインポートをバンドラーが解決できません

予想外の動作：

• build.rollupOptions は Vite 8 でも非推奨のエイリアスとして引き続き解決されるため、Rolldown 専用のオプションが必要になるまでは Vite 7 の設定が動作しているように見えます
• resolve.tsconfigPaths はデフォルトで無効です。有効化は意図的に行うものであり、フォールバックではありません
• Rolldown は、コード分割されたグループに加えて runtime.js チャンクも出力します
• loadEnv(mode, cwd, "") は、プレフィックスの有無にかかわらずファイル内のすべての変数を読み込みます。そのうちの一つを define でインライン化すると、バンドル内で公開されます
• Rolldown が CommonJS をネイティブに処理するため、Vite 8 では build.commonjsOptions は何も行いません
• Vite 8 では esbuild オプションが自動的に oxc に変換され、Oxc に同等の機能がないオプションは通知なく破棄されます
• ソースマップを有効にしたまま本番環境へデプロイすると、読み取り可能なソースが公開されます。'hidden' にすると、バンドルからリンクせずにエラー報告用のソースマップを保持できます

</red_flags>