vite-v8

Vite 8 スキル

リポジトリで推奨されている Vite ネイティブのパターンを使って、Vite 8 プロジェクトを設定、移行、デバッグします。

始める前に

このスキルでは、一般的なバンドラーのアドバイスではなく、Vite 8 のアーキテクチャの変更に焦点を当てています。

指標	スキルなし	スキルあり
移行時間	約120分	約40分
よくある設定エラー	6件以上	0件
トークン使用量	多い（試行錯誤）	少ない（既知のパターン）

このスキルで防げる既知の問題

1. rolldownOptions が必要な Vite 8 の設定に rollupOptions を残すことによるビルドの失敗
2. oxc の代わりに esbuild を使用することで発生する、古い JS/TS 変換設定
3. 環境を考慮した API の代わりに、古い ssr の真偽値をチェックするプラグインコード
4. hotUpdate の代わりに非推奨の handleHotUpdate パターンを使うことによる HMR の不具合
5. Module Runner ではなく、古い ssrLoadModule の考え方による SSR／ランタイムの混乱
6. Rust↔JS プラグイン境界でフックフィルターが不足することによるパフォーマンス低下
7. バレルファイル、ウォームアップ不足、あいまいなインポート解決による起動の遅延やリクエストのウォーターフォール

クイックスタート

ステップ 1：型付きの Vite 8 設定から始める

// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({
  server: {
    port: 5173,
  },
  build: {
    target: 'baseline-widely-available',
    rolldownOptions: {
      output: {
        manualChunks: undefined,
      },
    },
  },
});

重要な理由： Vite 8 は Rolldown／Oxc 時代の設定とデフォルトを中心に構築されています。Vite 8 のオプションを使って defineConfig から始めることで、新しいアーキテクチャに古い Rollup／esbuild の前提を持ち込まずに済みます。

ステップ 2：プラグインと SSR コードでは Vite 8 の用語を優先する

import type { Plugin } from 'vite';

export function inspectEnvironment(): Plugin {
  return {
    name: 'inspect-environment',
    configEnvironment(name) {
      if (name === 'ssr') {
        return {
          resolve: {
            conditions: ['node'],
          },
        };
      }
    },
  };
}

重要な理由： Vite 8 では、名前付き環境と環境を考慮したプラグインの動作が重視されます。これは、古いクライアントと SSR の簡易的な切り分けよりも適しています。

ステップ 3：適切なワンショットコマンドを使う

vite dev
vite build
vite build --ssr src/entry-server.ts
vite preview

重要な理由： これらは、エージェントと CI ワークフローが利用すべき安定したコマンドのインターフェースです。プロジェクトですでに使われている場合を除き、フレームワーク固有の抽象化を独自に作らないでください。

重要なルール

必ず行うこと

• リポジトリに関わる Vite 8 の作業では、defineConfig を使った vite.config.ts を使用します
• 従来の build.rollupOptions より build.rolldownOptions を優先します
• 新しい Vite 8 の変換設定では、esbuild より oxc を優先します
• プラグインまたは SSR の動作がランタイムによって異なる場合は、名前付き環境を使用します
• パフォーマンスが重要な transform または resolveId プラグインを書く場合は、フックフィルターを使用します
• 最新の SSR／ランタイム実行をデバッグする際は、Module Runner の概念を活用します
• パフォーマンスが重要な場合は、明示的なファイル拡張子を使用し、バレルファイルを確認します
• Vite プラグインのコードは ESM を優先します

絶対に行わないこと

• Vite 8 で推奨される方法として、新たに rollupOptions／esbuild の例を導入しないでください
• Vite 8 で将来も使われる HMR フックとして、handleHotUpdate を扱わないでください
• クライアントと SSR の単一の切り分けですべてのランタイムに対応できると想定しないでください
• 新しい Vite の作業で、CommonJS 設定をデフォルトとして提案しないでください
• SSR の依存関係に問題がある場合に、ssr.noExternal の確認を省略しないでください

よくある間違い

誤り — 古いビルド設定：

export default defineConfig({
  build: {
    rollupOptions: {
      external: ['react'],
    },
  },
  esbuild: {
    jsxInject: "import React from 'react'",
  },
});

正しい — Vite 8 の設定：

export default defineConfig({
  build: {
    rolldownOptions: {
      external: ['react'],
    },
  },
  oxc: {
    jsxInject: "import React from 'react'",
  },
});

理由： Vite 8 では、推奨されるビルドおよび変換設定のインターフェースが Rolldown と Oxc に移行しました。

誤り — 古い HMR フック：

export default function plugin() {
  return {
    name: 'old-hmr',
    handleHotUpdate(ctx) {
      return ctx.modules;
    },
  };
}

正しい — 環境を考慮した HMR：

export default function plugin() {
  return {
    name: 'env-hmr',
    hotUpdate(ctx) {
      return ctx.modules;
    },
  };
}

理由： hotUpdate は環境を考慮した Vite 8 の方向性であり、handleHotUpdate は従来の方式です。

既知の問題の防止

問題	根本原因	解決策
設定の移行が滞る	古い Rollup/esbuild の設定をそのまま引き継いでいる	rolldownOptions と oxc に移行します
標準外のランタイムでプラグインのロジックが動作しない	プラグインがクライアント／SSR のみを想定している	名前付きの environments と this.environment を使用します
HMR のカスタマイズが不安定に感じられる	旧式の HMR フックを引き継いでいる	hotUpdate と環境に応じたフローを優先します
SSR の依存関係でクラッシュする	外部化に関する前提が誤っている	ssr.noExternal とランタイム固有の要件を確認します
開発時とビルド時の動作が異なる	Vite 8 の統一エンジンモデルが設定に反映されていない	Rolldown のもとで vite dev と vite build の両方を検証します
プラグインのパフォーマンスが低下する	JavaScript 側でフックの処理を行いすぎている	フックフィルターを追加し、一致条件を絞り込みます
コールドスタートが遅い	負荷の高いホットパスがウォームアップされておらず、インポートグラフが煩雑になっている	server.warmup、拡張子の明示、バレルファイルの使用状況を確認します

同梱リソース

リファレンス

• コア設定と CLI のパターン → references/core-config-reference.md
• 環境に応じたプラグインの作成 → references/plugin-environment-reference.md
• ビルド、SSR、移行に関するガイダンス → references/build-ssr-migration-reference.md
• パフォーマンスと開発サーバーのヒューリスティクス → references/performance-devserver-reference.md
• リファレンスの目次 → references/README.md

設定リファレンス

vite.config.ts

import { defineConfig } from 'vite';

export default defineConfig({
  build: {
    target: 'baseline-widely-available',
    rolldownOptions: {
      output: {
        chunkFileNames: 'assets/[name]-[hash].js',
      },
    },
  },
  oxc: {
    jsxInject: "import React from 'react'",
  },
  environments: {
    ssr: {
      resolve: {
        conditions: ['node'],
      },
    },
  },
  css: {
    lightningcss: {},
  },
});

主な設定：

• build.rolldownOptions：Vite 8 で推奨されるビルドのカスタマイズ方法
• oxc：新しい Vite 8 の例で推奨される JS/TS トランスフォームの設定方法
• environments：クライアント／SSR／エッジ系ターゲット間でランタイムの動作が異なる場合に使用します
• css.lightningcss：Vite 8 の最新の CSS 処理方針を反映します
• server.warmup：コールドスタート時に同じホットファイルへのアクセスが繰り返される大規模アプリで役立ちます

プロジェクト構成

my-app/
├── src/
├── index.html
├── vite.config.ts
├── package.json
└── tsconfig.json

これが重要な理由： Vite 8 でも、シンプルで明示的なプロジェクト構成が効果を発揮します。複雑さは、コア設定を隠すのではなく、ランタイム環境やプラグインの境界から生じるべきです。

パフォーマンスのヒューリスティクス： 起動が遅いと感じたら、特殊なバンドラーのフラグを追う前に、インポートグラフの形状を確認してください。バレルファイル、拡張子の省略、ウォームアップの不足は、設定をさらに工夫するよりも影響が大きいことがよくあります。

一般的なパターン

環境に応じたプラグインのパターン

import type { Plugin } from 'vite';

export function envAwarePlugin(): Plugin {
  return {
    name: 'env-aware-plugin',
    transform: {
      filter: {
        id: /\.(ts|tsx)$/,
      },
      handler(code, id) {
        return {
          code,
          map: null,
        };
      },
    },
    configEnvironment(name) {
      if (name === 'ssr') {
        return {
          resolve: {
            conditions: ['node'],
          },
        };
      }
    },
  };
}

SSR ビルドのパターン

vite build
vite build --ssr src/entry-server.ts
vite preview

Module Runner のメンタルモデル

// Pseudocode sketch
const mod = await moduleRunner.import('/src/entry-server.ts');

最新の Vite における SSR のデバッグで、単純なバンドルではなくランタイムの実行境界が問題になっている場合は、このモデルを使用してください。

依存関係

必須

パッケージ	バージョン	用途
vite	^8	ビルドツール、開発サーバー、プラグインホスト
node	>=20.19 or >=22.12	Vite 8 の必須ランタイム

オプション

パッケージ	バージョン	用途
typescript	latest	型付きの vite.config.ts とプラグインの作成
framework plugin packages	latest	React/Vue/Svelte などとの統合

公式ドキュメント

• Vite ドキュメント
• LLM インデックス
• 設定リファレンス
• プラグイン API
• ビルドガイド
• SSR ガイド
• 環境 API

トラブルシューティング

古い設定キーがしっくりこない

症状： 設定は動作するものの、Vite 8 より前のコードのように見える場合や、新しいオプションが期待どおりに動作しない場合があります。

解決策：

build: {
  rolldownOptions: {},
}

oxc: {}

SSR のランタイム動作が不明確

症状： バンドルはビルドされますが、実行時の動作が環境やプラットフォームによって異なります。

解決策： 関連のないバンドラー設定を変更する前に、environments、this.environment、Module Runner の要件、ssr.noExternal を確認してください。

プラグインフックの処理が遅い、または煩雑に感じる

症状： カスタムプラグインによって、開発時やビルド時のオーバーヘッドが増加します。

解決策： フックフィルターと対象を絞ったマッチングパターンを使用し、関連するファイルのみが Rust↔JS 境界を越えるようにしてください。

セットアップチェックリスト

このスキルを使用する前に、以下を確認してください。

• vite が Vite 8 系のリリースである
• Node が Vite 8 のランタイム要件を満たしている
• vite.config.ts が ESM／TypeScript を優先している
• 従来の rollupOptions／esbuild の使用状況を確認している
• SSR／エッジランタイムが関係する場合、環境固有の動作を明示的にモデル化している