# バッチ設計書 16-turbo dev

## 概要

本ドキュメントは、Tailwind CSSプロジェクトにおけるTurborepoを使用した開発モード一括起動コマンド「turbo dev」のバッチ設計書である。全パッケージの開発モードを一括起動し、ソースコード変更時の自動再ビルドを提供する。

### 本バッチの処理概要

本バッチは、Tailwind CSSモノレポ内の全パッケージの開発モードをTurborepoのオーケストレーション機能を使用して一括起動するコマンドである。`pnpm run dev`として実行され、内部的に`turbo dev --filter=!./playgrounds/*`が呼び出される。

**業務上の目的・背景**：Tailwind CSSの開発作業では、複数のパッケージを同時に開発モードで起動し、ソースコード変更時の自動再ビルドが必要である。個別のパッケージを手動で開発モード起動すると、依存関係の解決やプロセス管理が煩雑になる。Turborepoを使用することで、全パッケージの開発モードを一括で起動し、依存関係に基づいた適切な順序での再ビルドを自動化する。開発者はこのコマンド1つで開発環境を即座に構築できる。

**バッチの実行タイミング**：開発者がローカル開発環境で`pnpm run dev`を手動実行した時に起動される。永続実行モードで動作し、明示的に停止するまで実行を継続する。

**主要な処理内容**：
1. turbo.jsonの設定に基づく依存関係グラフの構築
2. @tailwindcss/oxide パッケージの開発モード起動（ファイル監視つき）
3. 各パッケージのdevタスクの永続実行（キャッシュなし）
4. ソースコード変更時の自動再ビルド

**前後の処理との関連**：turbo build（No.15）が本番ビルドを担当するのに対し、本バッチは開発中の継続的ビルドを担当する。開発者は本バッチを実行しながらplaygroundsパッケージ（例: vite-playground、nextjs-playground）を別途起動して動作確認を行う。

**影響範囲**：全ワークスペースパッケージ（playgroundsを除く）のビルド成果物。ローカル開発環境のプロセス。キャッシュは使用されないため、Turborepoキャッシュへの影響はない。

## バッチ種別

ビルドオーケストレーション（開発モード）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（開発者の手動実行） |
| 実行時刻 | 不定 |
| 実行曜日 | 不定 |
| 実行日 | 不定 |
| トリガー | 手動（pnpm run dev） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| pnpmがインストール済み | パッケージマネージャとしてpnpm v9.6.0以上が必要 |
| Node.jsが利用可能 | Node.js v24推奨 |
| Rustツールチェーンがインストール済み | @tailwindcss/oxideの開発モードビルドにRustが必要 |
| 依存関係がインストール済み | pnpm installが完了していること |
| turboがインストール済み | devDependenciesとしてturbo v2.7.6以上がインストール済み |

### 実行可否判定

前提条件がすべて満たされている場合に実行可能。キャッシュは使用されないため、常にフルビルドから開始される。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| RUSTUP_HOME | string | No | ~/.rustup | Rustupのホームディレクトリ（globalPassThroughEnvで透過） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| turbo.json | JSONC | Turborepoのタスク定義・依存関係・キャッシュ設定 |
| package.json（ルート） | JSON | devスクリプト定義（turbo dev --filter=!./playgrounds/*） |
| package.json（各パッケージ） | JSON | 各パッケージのdevスクリプト定義 |
| pnpm-workspace.yaml | YAML | ワークスペースパッケージの定義 |
| 各パッケージのソースコード | TypeScript/Rust/CSS | 監視対象のソースコード |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| packages/*/dist/ | JavaScript/TypeScript定義/CSS | 各パッケージの開発ビルド成果物（変更時に自動更新） |
| crates/node/*.node | バイナリ | @tailwindcss/oxideのネイティブバイナリ（変更時に自動再ビルド） |
| crates/node/index.js, index.d.ts | JavaScript/TypeScript | @tailwindcss/oxideのJSバインディング |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | dist/**（各パッケージ内）、*.node（Oxide） |
| 出力先 | 各パッケージディレクトリ内 |
| 文字コード | UTF-8（JavaScript/TypeScript）/ バイナリ（.node） |
| 区切り文字 | N/A |

## 処理フロー

### 処理シーケンス

```
1. turbo devコマンド開始
   └─ --filter=!./playgrounds/* でplaygroundsパッケージを除外
2. 依存関係グラフの構築
   └─ turbo.jsonの設定に基づきタスク間の依存関係を解析
3. @tailwindcss/oxide 開発モード起動
   ├─ Rustソースコードの初回ビルド
   ├─ ファイル監視開始（src/**, build.rs, Cargo.toml等）
   ├─ persistent: true で永続実行
   └─ cache: false でキャッシュ無効
4. 依存パッケージの開発モード起動（依存関係順）
   ├─ 各パッケージのdevタスク起動
   ├─ persistent: true で永続実行
   └─ cache: false でキャッシュ無効
5. ファイル監視状態で待機
   ├─ ソースコード変更検知時に該当パッケージを再ビルド
   └─ 依存先パッケージの変更時は依存元パッケージも再ビルド
6. ユーザーによる明示的停止（Ctrl+C等）まで継続
```

### フローチャート

```mermaid
flowchart TD
    A[pnpm run dev] --> B[turbo dev --filter=!./playgrounds/*]
    B --> C[依存関係グラフ構築]
    C --> D[@tailwindcss/oxide 開発モード起動]
    D --> E[依存パッケージの開発モード一括起動]
    E --> F[ファイル監視状態で待機]
    F --> G{ソースコード変更検知?}
    G -->|Yes| H[変更パッケージの再ビルド]
    H --> I[依存元パッケージの再ビルド]
    I --> F
    G -->|No| J{停止シグナル?}
    J -->|Yes| K[全プロセス停止]
    J -->|No| F
    K --> L[コマンド終了]
```

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

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

本バッチはデータベースを使用しない。

| 処理 | 対象 | 操作種別 | 概要 |
|-----|------|---------|------|
| N/A | N/A | N/A | データベース操作なし |

### テーブル別操作詳細

N/A（データベース操作なし）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| RUST_BUILD_FAIL | Rustビルドエラー | @tailwindcss/oxideのRustコンパイルエラー | Rustソースコードを修正（自動再ビルド） |
| TS_BUILD_FAIL | TypeScriptビルドエラー | TypeScriptコンパイルエラー | TypeScriptソースコードを修正（自動再ビルド） |
| DEP_MISSING | 依存関係エラー | pnpm installが未実行 | pnpm installを実行後に再起動 |
| PORT_CONFLICT | ポート競合 | 既存プロセスがポートを使用中 | 既存プロセスを停止してから再起動 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | ファイル変更検知時に自動再ビルド（永続実行） |
| リトライ間隔 | ファイル変更検知後即時 |
| リトライ対象エラー | ビルドエラー（ソースコード修正後に自動再試行） |

### 障害時対応

1. ビルドエラー時：永続実行モードのため、ソースコードを修正すれば自動的に再ビルドが実行される。プロセス停止は不要。
2. 起動失敗時：依存関係のインストール状況を確認し、pnpm installを再実行する。
3. プロセスが応答しない場合：Ctrl+Cで停止し、再起動する。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | N/A（開発モードのためトランザクション管理なし） |
| コミットタイミング | N/A |
| ロールバック条件 | N/A |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | ワークスペース内の全パッケージ（playgrounds除外） |
| 目標処理時間 | 初回起動: フルビルド相当 / 変更検知時の再ビルド: 数秒以内 |
| メモリ使用量上限 | 全パッケージの監視プロセスが常駐するため、Rustコンパイル時に数GB使用の可能性あり |

## 排他制御

Turborepoが内部的にタスクの並列実行と排他制御を管理する。persistent: trueにより各タスクは永続実行され、Turborepoの管理下でプロセスが維持される。同一パッケージのdevタスクが複数同時に実行されることはない。

注意: `pnpm run dev`を複数ターミナルから同時に実行するとポート競合やファイルロック問題が発生する可能性がある。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | turboコマンド実行時 | Turborepo TUI（ui: "tui"）による進捗表示 |
| ビルドログ | 初回ビルド/再ビルド時 | 各パッケージのビルドステータス |
| 監視ログ | ファイル変更検知時 | 変更されたファイル、再ビルド対象パッケージ |
| エラーログ | ビルドエラー時 | エラー詳細（ソースコード修正後に自動再試行） |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| N/A | N/A | ターミナル出力（ローカル開発用のためアラート設定なし） |

## 備考

- turbo.jsonでは以下の開発モードタスク定義がある：
  - `dev`: 汎用開発タスク。`cache: false`（キャッシュ無効）、`persistent: true`（永続実行）。
  - `@tailwindcss/oxide#dev`: Oxide専用開発タスク。`dependsOn: ["^dev"]`で依存パッケージの開発モードを先行起動。`cache: false`、`persistent: true`。出力はindex.d.ts、index.js、*.node。入力はbuildタスクと同一のRust関連ファイル。
- turbo buildとの主な違い：
  - `cache: false`: キャッシュが使用されないため、毎回フルビルドから開始される
  - `persistent: true`: プロセスが永続実行され、停止するまでファイル監視を継続する
  - `FEATURES_ENV`環境変数の監視がない: devタスクには環境変数の監視設定がない
  - postbuildスクリプト（pack-packages.mjs）は実行されない: devスクリプトにはpostdev定義がないため
- package.jsonの`dev`スクリプトは`turbo dev --filter=!./playgrounds/*`であり、playgroundsパッケージが対象から除外される。
- playgroundsの起動は別コマンド（`pnpm run vite`や`pnpm run nextjs`）で行う。
- UIモードは`tui`（Terminal User Interface）が設定されており、ターミナルでのリッチな進捗表示が有効。
- `globalPassThroughEnv: ["RUSTUP_HOME"]`により、Rustupが標準以外のディレクトリにインストールされている場合もパスが透過される。
