# 機能設計書 52-Viteプラグイン（@tailwindcss/vite）

## 概要

本ドキュメントは、ViteビルドシステムにTailwind CSSを統合するプラグイン `@tailwindcss/vite` の機能設計を記述する。開発サーバーでのHMR対応、ビルドモードでのCSS最適化、SSRサポートを提供する。

### 本機能の処理概要

**業務上の目的・背景**：Viteは近年のフロントエンド開発において広く採用されているビルドツールであり、多くのプロジェクトがViteベースで構築されている。`@tailwindcss/vite` は、ViteのプラグインAPIを活用してTailwind CSSのコンパイル処理をビルドパイプラインにシームレスに統合し、開発時のHMR（Hot Module Replacement）による高速なスタイル反映と、本番ビルド時のCSS最適化を提供する。

**機能の利用シーン**：vite.config.tsにおいて `@tailwindcss/vite` をプラグインとして登録し、CSSファイル変更時の自動リビルドと開発サーバーでのリアルタイムスタイル反映を行う。Vue、React、Svelte等のViteベースプロジェクトで使用される。

**主要な処理内容**：
1. Vite configResolved フックでの設定解決（SSR検出、最適化オプション決定）
2. CSSファイルのtransformフックでのTailwind CSSコンパイル
3. serve/buildモード別のCSS生成戦略
4. HMR対応：外部ファイル変更時のフルリロードトリガー
5. Root クラスによるCSSファイル単位のコンパイラ・スキャナ管理
6. 環境（Environment）APIによるマルチ環境対応
7. ビルドモードでのLightning CSS最適化
8. ソースマップ生成（開発モードでdevSourcemap有効時）

**関連システム・外部連携**：Vite Plugin API、Vite Environment API、@tailwindcss/node（compile・optimize・toSourceMap）、@tailwindcss/oxide（Scanner）、Lightning CSS（最適化）

**権限による制御**：特になし。Viteの設定（build.cssMinify等）により最適化の挙動が制御される。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | トップページ | 主画面 | vite.config.tsでtailwindcss()プラグインが登録されており、Viteビルド時にTailwind CSSの処理を統合する |

## 機能種別

データ変換処理（CSSソース -> Tailwind CSSコンパイル -> 最適化CSS出力）/ リアルタイム監視

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| optimize | boolean \| { minify?: boolean } | No | CSS最適化・ミニファイの有無。ビルド時はデフォルトtrue | - |

### 入力データソース

- Viteのtransformフック経由で渡されるCSSソース文字列
- ファイルシステム上のCSSファイル
- ソースファイル群（Scannerがglobパターンでスキャン）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| code | string | コンパイル済みCSS文字列 |
| map | string \| undefined | ソースマップ（devSourcemap有効時のみ） |

### 出力先

Viteのtransformフックの戻り値として次の処理へ渡される

## 処理フロー

### 処理シーケンス

```
1. configResolved: Vite設定の解決
   └─ SSR検出、最適化オプション、ミニファイ設定の決定
2. transform (serve/build): CSSファイルの検出
   └─ .cssファイルかつ特殊クエリなしの場合に処理
3. Root取得/作成
   └─ 環境名+ファイルIDをキーにRootインスタンスを管理
4. Root.generate(): CSS生成
   └─ a. コンパイラの初期化/リビルド判定
   └─ b. compile()でTailwind CSSコンパイラ作成
   └─ c. Scanner初期化とソースパターン構築
   └─ d. 候補クラスのスキャンと蓄積
   └─ e. compiler.build()でCSS生成
   └─ f. ソースマップ生成（有効時）
5. 最適化（buildモードかつoptimize有効時）
   └─ Lightning CSSによる最適化
6. hotUpdate: 外部ファイル変更時のフルリロード
   └─ スキャン対象ファイルの変更をViteモジュールグラフ経由で検知
```

### フローチャート

```mermaid
flowchart TD
    A[Vite transform hook] --> B{CSSファイル?}
    B -->|No| C[スキップ]
    B -->|Yes| D{特殊クエリ?}
    D -->|Yes| C
    D -->|No| E[Root取得/作成]
    E --> F[Root.generate]
    F --> G{コンパイラ初期化/リビルド必要?}
    G -->|Yes| H[compile でコンパイラ作成]
    G -->|No| I[既存コンパイラ使用]
    H --> J[Scanner初期化]
    I --> K[候補クラスのスキャン]
    J --> K
    K --> L[compiler.build でCSS生成]
    L --> M{ソースマップ有効?}
    M -->|Yes| N[ソースマップ生成]
    M -->|No| O{buildモード & optimize?}
    N --> O
    O -->|Yes| P[Lightning CSSで最適化]
    O -->|No| Q[結果返却]
    P --> Q
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-52-01 | CSSファイル判定 | .css拡張子、&lang.css、インラインスタイルIDを持つファイルのみ処理対象 | transformフック実行時 |
| BR-52-02 | 特殊クエリ除外 | worker、sharedworker、raw、urlクエリを含むIDは処理対象外 | transformフック実行時 |
| BR-52-03 | .viteディレクトリ除外 | Vite内部のキャッシュディレクトリ内のファイルは処理対象外 | transformフック実行時 |
| BR-52-04 | commonjs-proxy除外 | CommonJSプロキシファイルは処理対象外 | transformフック実行時 |
| BR-52-05 | フルリビルド判定 | 依存ファイル（CSS、プラグイン）のmtimeが変更されたらコンパイラを再作成 | generate実行時 |
| BR-52-06 | インクリメンタル候補蓄積 | スキャン済み候補クラスはSetで蓄積し、重複排除する | generate実行時 |
| BR-52-07 | SVGファイルのウォッチ除外 | パスに#や?を含むSVGファイルはaddWatchFile対象外（Viteクラッシュ回避） | addWatchFile呼び出し時 |
| BR-52-08 | HMR外部ファイル検知 | モジュールグラフに含まれないがスキャン対象のファイル変更時、フルリロードをトリガー | hotUpdateフック実行時 |

### 計算ロジック

特になし

## データベース操作仕様

### 操作別データベース影響一覧

該当なし（データベース操作は行わない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | source()パスエラー | source(...)で指定されたパスがディレクトリでない場合 | エラーメッセージを投げる |
| - | スタイルシート読み込みエラー | @importの解決に失敗した場合 | コンパイラのエラーハンドリングに委譲 |

### リトライ仕様

明示的なリトライは行わない。依存ファイルの変更検知によりリビルドが自動的に行われる。

## トランザクション仕様

該当なし

## パフォーマンス要件

- Root単位でコンパイラ・スキャナをキャッシュし、依存ファイル変更時のみリビルド
- 候補クラスをSetで蓄積し、インクリメンタルなスキャンによりパフォーマンスを向上
- buildモードでのみLightning CSS最適化を実行（devモードでは省略）
- DefaultMapによる環境別Rootインスタンスの遅延初期化

## セキュリティ考慮事項

- カスタムCSSリゾルバ・JSリゾルバはViteの設定に基づいて構築される
- clearRequireCacheにより依存モジュールのキャッシュを適切にクリア

## 備考

- 3つのViteプラグインとして登録される：`@tailwindcss/vite:scan`（pre enforce）、`@tailwindcss/vite:generate:serve`（serve専用）、`@tailwindcss/vite:generate:build`（build専用）
- Vite Environment API（Vite v6+）とレガシーAPIの両方に対応
- Vite v7のモジュール無効化挙動の変更にも対応済み

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/@tailwindcss-vite/src/index.ts` | PluginOptions型（29-34行目）、Root クラス（340-551行目）の定義を確認 |
| 1-2 | index.ts | `packages/@tailwindcss-vite/src/index.ts` | DefaultMap ヘルパークラス（323-338行目）を確認 |

**読解のコツ**: Rootクラスが1つのCSSファイルに対するコンパイラ・スキャナ・候補クラスの状態を保持する。rootsByEnvがEnvironment別にRootインスタンスを管理する構造を理解すること。

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/@tailwindcss-vite/src/index.ts` | tailwindcss関数（36-295行目）が3つのPlugin配列を返す構造を確認 |

**主要処理フロー**:
1. **36-43行目**: プラグイン状態の初期化（servers, config, rootsByEnv, isSSR, shouldOptimize, minify）
2. **45-121行目**: createRoot関数 - Environment APIとレガシーAPIの両対応
3. **123-152行目**: `@tailwindcss/vite:scan` プラグイン - configResolved, configureServer
4. **154-247行目**: `@tailwindcss/vite:generate:serve` プラグイン - serve時のtransform + hotUpdate
5. **249-293行目**: `@tailwindcss/vite:generate:build` プラグイン - build時のtransform + optimize

#### Step 3: Root.generate メソッドを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.ts | `packages/@tailwindcss-vite/src/index.ts` | Root.generate（373-527行目）: CSS生成のメインロジック |

**主要処理フロー**:
- **403-406行目**: コンパイラ/スキャナの初期化判定とリビルド要否チェック
- **414-425行目**: compile()でコンパイラ作成、依存関係の追跡
- **431-447行目**: Scanner初期化とソースパターン構築
- **454-461行目**: Features検査でTailwind CSS機能が使われていなければfalseを返す
- **463-472行目**: scanner.scan()で候補クラスをSetに蓄積
- **474-513行目**: ファイル・globの監視登録、source(...)パスの検証
- **515-521行目**: compiler.build()とソースマップ生成

#### Step 4: HMR処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | index.ts | `packages/@tailwindcss-vite/src/index.ts` | hotUpdate関数（190-246行目）: 外部ファイル変更検知とフルリロード |
| 4-2 | index.ts | `packages/@tailwindcss-vite/src/index.ts` | isScannedFile関数（553-602行目）: モジュールグラフの逆走査 |

### プログラム呼び出し階層図

```
tailwindcss() [Viteプラグイン登録]
    |
    +-- @tailwindcss/vite:scan
    |       +-- configResolved()  [設定解決]
    |       +-- configureServer() [サーバー参照保持]
    |
    +-- @tailwindcss/vite:generate:serve
    |       +-- transform()
    |       |       +-- createRoot()      [Root作成]
    |       |       +-- Root.generate()   [CSS生成]
    |       |               +-- compile() [@tailwindcss/node]
    |       |               +-- Scanner.scan()
    |       |               +-- compiler.build()
    |       |               +-- toSourceMap()
    |       |
    |       +-- hotUpdate()
    |               +-- isScannedFile()   [変更ファイル検証]
    |               +-- environment.hot.send() [フルリロード]
    |
    +-- @tailwindcss/vite:generate:build
            +-- transform()
                    +-- Root.generate()   [CSS生成]
                    +-- optimize()        [Lightning CSS]
```

### データフロー図

```
[入力]                      [処理]                          [出力]

CSS ソース文字列  ───▶  compile(content)  ───▶  compiler (build関数)
                                |
                                v
ソースファイル群   ───▶  Scanner.scan()    ───▶  候補クラスSet
                                |
                                v
                        compiler.build()  ───▶  CSS文字列
                                |
                                v
                [devSourcemap]  toSourceMap()  ───▶  ソースマップ
                [build+opt]    optimize()     ───▶  最適化CSS
                                |
                                v
                        { code, map }     ───▶  Vite transformフック戻り値
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/@tailwindcss-vite/src/index.ts` | ソース | Viteプラグインのメインエントリーポイント |
| compile.ts | `packages/@tailwindcss-node/src/compile.ts` | ソース | Node.js向けコンパイララッパー |
| optimize.ts | `packages/@tailwindcss-node/src/optimize.ts` | ソース | Lightning CSSによるCSS最適化 |
| source-maps.ts | `packages/@tailwindcss-node/src/source-maps.ts` | ソース | ソースマップのシリアライズ |
| normalize-path.ts | `packages/@tailwindcss-node/src/normalize-path.ts` | ソース | パス正規化ユーティリティ |
| instrumentation.ts | `packages/@tailwindcss-node/src/instrumentation.ts` | ソース | デバッグ用パフォーマンス計測 |
