# 機能設計書 16-@babel/preset-react

## 概要

本ドキュメントは、Babelの@babel/preset-reactパッケージの機能設計を記述する。@babel/preset-reactは、React/JSXの変換に必要なプラグインをまとめたプリセットである。

### 本機能の処理概要

@babel/preset-reactは、JSX構文をJavaScriptに変換するために必要なBabelプラグインを提供する。React 17以降の新しいJSXランタイム（automatic runtime）と従来のReact.createElement呼び出し（classic runtime）の両方をサポートする。

**業務上の目的・背景**：ReactアプリケーションではJSX構文が広く使用されている。JSXはブラウザが直接理解できないため、React.createElement呼び出しまたは新しいjsx関数呼び出しに変換する必要がある。@babel/preset-reactは、この変換に必要なプラグインを統合し、開発モードでのデバッグ情報追加やdisplayName設定などのReact特有の最適化も行う。

**機能の利用シーン**：Reactアプリケーションのビルド、React Nativeアプリケーションのビルド、Preact等の他のJSXベースライブラリのビルドなどで利用される。

**主要な処理内容**：
1. JSX構文の変換（@babel/plugin-transform-react-jsx）
2. 開発モード用のJSX変換（@babel/plugin-transform-react-jsx-development）
3. displayNameの自動追加（@babel/plugin-transform-react-display-name）
4. pure注釈の追加（@babel/plugin-transform-react-pure-annotations）
5. classicとautomaticのランタイムモード切り替え

**関連システム・外部連携**：@babel/plugin-transform-react-jsx、@babel/plugin-transform-react-jsx-development、@babel/plugin-transform-react-display-name、@babel/plugin-transform-react-pure-annotationsと連携。

**権限による制御**：本機能に権限制御は存在しない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | Babelトランスフォームデモ | 補助機能 | JSX構文の変換に使用（presetsに"react"を指定） |
| 2 | インラインスクリプトタグデモ | 補助機能 | デフォルトプリセットとしてJSX構文をサポート |
| 3 | 外部スクリプトタグデモ | 補助機能 | デフォルトプリセットとしてJSX構文をサポート |
| 4 | カスタムスクリプトタグデモ | 補助機能 | デフォルトプリセットとしてJSX構文をサポート |

## 機能種別

プリセット / JSX変換

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| runtime | string | No | JSXランタイムモード | "automatic" または "classic"（デフォルト: "automatic"） |
| development | boolean | No | 開発モード | デフォルト: 環境変数から判定 |
| importSource | string | No | JSX関数のインポート元 | デフォルト: "react" |
| pragma | string | No | JSX変換関数（classic） | デフォルト: "React.createElement" |
| pragmaFrag | string | No | Fragment変換関数（classic） | デフォルト: "React.Fragment" |
| throwIfNamespace | boolean | No | 名前空間付きJSXでエラー | デフォルト: true |
| pure | boolean | No | pure注釈を追加 | デフォルト: true |

### 入力データソース

- Babel設定ファイル（babel.config.js, .babelrc等）
- API呼び出しのオプション

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| plugins | array | 適用するプラグインの配列 |

### 出力先

Babelコア(@babel/core)に対してプラグイン配列を返却する。

## 処理フロー

### 処理シーケンス

```
1. オプションの正規化
   └─ normalizeOptions: デフォルト値設定
   └─ development: api.env()で環境判定

2. プラグインの選択
   └─ development: true → transform-react-jsx-development
   └─ development: false → transform-react-jsx

3. displayNameプラグインの追加
   └─ 常に transform-react-display-name を追加

4. pure注釈プラグインの追加
   └─ pure !== false → transform-react-pure-annotations を追加

5. プラグイン配列の返却
```

### フローチャート

```mermaid
flowchart TD
    A[preset-react呼び出し] --> B[normalizeOptions]
    B --> C{development?}
    C -->|Yes| D[jsx-development プラグイン]
    C -->|No/undefined| E{api.env判定}
    E -->|development| D
    E -->|production| F[jsx プラグイン]
    D --> G[display-name プラグイン追加]
    F --> G
    G --> H{pure !== false?}
    H -->|Yes| I[pure-annotations プラグイン追加]
    H -->|No| J[プラグイン配列返却]
    I --> J
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | runtime: automatic | React 17+の新しいJSXランタイムを使用 | runtime未指定またはautomatic |
| BR-02 | runtime: classic | React.createElementを使用 | runtime: "classic" |
| BR-03 | 開発モード判定 | api.env("development")でdevelopmentかどうか判定 | development未指定時 |
| BR-04 | displayName追加 | コンポーネントにdisplayNameを自動設定 | 常時 |
| BR-05 | pure注釈 | JSX呼び出しに/*#__PURE__*/を追加 | pure: true（デフォルト） |

### 計算ロジック

JSX変換例:
```javascript
// 入力（JSX）
<div className="container">Hello</div>

// 出力（automatic runtime）
import { jsx as _jsx } from "react/jsx-runtime";
_jsx("div", { className: "container", children: "Hello" });

// 出力（classic runtime）
React.createElement("div", { className: "container" }, "Hello");
```

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

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Error | 名前空間付きJSX使用時 | throwIfNamespace: false を設定 |
| - | Error | 無効なruntime値 | "automatic"または"classic"を指定 |

### リトライ仕様

本機能にリトライ処理は存在しない。

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

本機能はトランザクション処理を行わない。

## パフォーマンス要件

- プリセット初期化は軽量
- 各プラグインの実行時間は変換コードサイズに比例

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

- importSourceで任意のパッケージを指定可能（信頼できるソースのみ使用）
- JSXはユーザー入力を直接含まない前提

## 備考

- React 17以降ではautomatic runtimeがデフォルト推奨
- Preact使用時はimportSource: "preact"と設定
- useBuiltIns、useSpreadオプションはBabel 8で廃止予定

---

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

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

### 推奨読解順序

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

まず、プリセットのメイン処理を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/babel-preset-react/src/index.ts` | プリセットのメイン実装 |

**読解のコツ**:
- **1-7行目**: インポート文。各プラグインとnormalizeOptionsをインポート
- **9-19行目**: Optionsインターフェース定義
- **21-52行目**: declarePreset関数。プリセットのメイン処理
- **25行目**: developmentのデフォルト値をapi.env()で判定
- **35-50行目**: プラグイン配列の構築

#### Step 2: プラグイン選択ロジックを理解する

開発/本番モードによるプラグイン切り替えを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/babel-preset-react/src/index.ts` | 37行目のternary演算子 |

**主要処理フロー**:
- **37行目**: development ? transformReactJSXDevelopment : transformReactJSX
- **39-46行目**: JSXプラグインへのオプション渡し
- **48行目**: displayNameプラグインは常に追加
- **49行目**: pure !== false の場合にpure-annotationsプラグイン追加

#### Step 3: オプション正規化を理解する

オプションの検証と正規化処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | normalize-options.ts | `packages/babel-preset-react/src/normalize-options.ts` | オプション正規化 |

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

```
@babel/preset-react
    │
    ├─ declarePreset (@babel/helper-plugin-utils)
    │
    ├─ normalizeOptions
    │      └─ オプションの検証と正規化
    │
    └─ plugins[]
           │
           ├─ @babel/plugin-transform-react-jsx
           │  または
           ├─ @babel/plugin-transform-react-jsx-development
           │
           ├─ @babel/plugin-transform-react-display-name
           │
           └─ @babel/plugin-transform-react-pure-annotations
```

### データフロー図

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

オプション ──────────> normalizeOptions ─────────────────┐
                                                        │
api.env() ───────────> development判定 ─────────────────┤
                                                        │
                                                        └──> plugins[]
                                                                │
JSXコード ──────────────────────────────────────────────────────┤
                                                                │
                                                        React.createElement
                                                        または
                                                        jsx/jsxs関数呼び出し
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/babel-preset-react/src/index.ts` | ソース | プリセットメイン実装 |
| normalize-options.ts | `packages/babel-preset-react/src/normalize-options.ts` | ソース | オプション正規化 |
| package.json | `packages/babel-preset-react/package.json` | 設定 | パッケージ設定 |
| test/index.js | `packages/babel-preset-react/test/index.js` | テスト | ユニットテスト |
| test/preset-options.js | `packages/babel-preset-react/test/preset-options.js` | テスト | プリセットオプションテスト |
