@aramassa/ai-rules 0.8.1 → 0.9.2

package/artifact/instructions/rules/development/npm-package-rollup-build.md

@@ -0,0 +1,883 @@
+---
+type: development-rules
+category: build
+framework: rollup
+language:
+  - typescript
+  - nodejs
+applyTo:
+  - "rollup.config.*"
+  - "package.json"
+  - "tsconfig*.json"
+---
+
+# npm Package Build with Rollup: 総合ルール
+
+このドキュメントは、Rollup を使用した npm パッケージビルドの標準ルールを定義します。
+TypeScript + Rollup + モノレポ構成での CLI ツールやライブラリの開発に適用されます。
+
+## 目次
+
+- [概要](#概要)
+- [前提条件と事前調査](#前提条件と事前調査)
+- [依存関係管理](#依存関係管理)
+- [Rollup 設定](#rollup-設定)
+- [TypeScript 設定](#typescript-設定)
+- [package.json 設定](#packagejson-設定)
+- [ビルドプロセス](#ビルドプロセス)
+- [配布物の品質確認](#配布物の品質確認)
+- [トラブルシューティング](#トラブルシューティング)
+- [ベストプラクティス](#ベストプラクティス)
+
+## 概要
+
+### Rollup の特徴と適用場面
+
+Rollup は ES モジュール用に設計されたバンドラーで、以下の特徴があります：
+
+1. **優れた Tree-shaking**: 使用されていないコードを精密に除去
+2. **小さなバンドルサイズ**: 特にライブラリやCLIツールで効果的
+3. **ES モジュールファースト**: モダンな JavaScript 開発に最適
+4. **多様な出力フォーマット**: ESM, CJS, UMD, IIFE など
+
+### 適用場面
+
+- **CLI ツール開発**: 単一実行ファイルの生成
+- **ライブラリ開発**: 小さなバンドルサイズと複数フォーマット対応
+- **モノレポ**: 複数パッケージの統合バンドル
+
+## 前提条件と事前調査
+
+### 実装前の確認事項
+
+1. **エントリーポイントの特定**
+   - CLI: `src/cli.ts`
+   - ライブラリ: `src/index.ts`
+
+2. **依存関係の分類**
+   - バンドル対象: プロジェクト固有のコード、小さな依存関係
+   - 外部化対象: ランタイム依存、大きなライブラリ（yaml, fs, pathなど）
+
+3. **出力フォーマットの決定**
+   - CLI: ESM（`format: 'esm'`）
+   - ライブラリ: ESM + CJS（複数出力）
+
+4. **モノレポ構成の確認**
+   - workspace パッケージの依存関係
+   - ビルド順序の決定
+
+5. **配布ファイル構成の決定**
+   - `dist/` ディレクトリ構成
+   - package.json の `files` フィールド内容
+
+## 依存関係管理
+
+### 必須パッケージ
+
+```bash
+# Rollup 本体とコア機能
+npm install --save-dev rollup
+
+# TypeScript サポート
+npm install --save-dev @rollup/plugin-typescript
+npm install --save-dev typescript
+npm install --save-dev tslib
+
+# モジュール解決
+npm install --save-dev @rollup/plugin-node-resolve
+npm install --save-dev @rollup/plugin-commonjs
+
+# その他の機能
+npm install --save-dev @rollup/plugin-json
+npm install --save-dev @rollup/plugin-alias  # モノレポの場合
+```
+
+### tslib の重要性
+
+**必須理由**:
+- `@rollup/plugin-typescript` が依存している
+- TypeScript ヘルパー関数の重複を防ぐ
+- バンドルサイズを大幅に削減
+
+**インストール場所**:
+```bash
+# ルートプロジェクト（必須）
+npm install --save-dev tslib
+
+# 各 workspace パッケージ（推奨）
+cd packages/core && npm install --save-dev tslib
+cd packages/common && npm install --save-dev tslib
+```
+
+**効果の例**:
+
+```typescript
+// tslib なし: 各ファイルでヘルパー関数が重複生成
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    // 長いヘルパー関数コード...
+};
+
+// tslib あり: 共有ライブラリから import
+import { __awaiter } from 'tslib';
+```
+
+## Rollup 設定
+
+### 基本設定（rollup.config.mjs）
+
+```javascript
+import { defineConfig } from 'rollup';
+import typescript from '@rollup/plugin-typescript';
+import nodeResolve from '@rollup/plugin-node-resolve';
+import commonjs from '@rollup/plugin-commonjs';
+import json from '@rollup/plugin-json';
+
+export default defineConfig({
+  input: 'src/index.ts',
+  output: {
+    file: 'dist/index.js',
+    format: 'esm',
+    sourcemap: false,
+  },
+  external: [],  // 外部化する依存関係
+  plugins: [
+    nodeResolve({ preferBuiltins: true }),
+    commonjs({ transformMixedEsModules: true }),
+    json(),
+    typescript({
+      tsconfig: './tsconfig.build.json',
+      outputToFilesystem: true,
+    }),
+  ],
+});
+```
+
+### CLI ツール向け設定
+
+```javascript
+export default defineConfig({
+  input: 'src/cli.ts',
+  output: {
+    file: 'dist/cli.js',
+    format: 'esm',
+    inlineDynamicImports: true,  // 動的インポートをインライン化
+    sourcemap: false,
+  },
+  external: ['yaml', 'fs', 'path'],  // ランタイム依存は外部化
+  plugins: [
+    nodeResolve({ preferBuiltins: true }),
+    commonjs({ transformMixedEsModules: true }),
+    json(),
+    typescript({
+      tsconfig: './tsconfig.build.json',
+      outputToFilesystem: true,
+    }),
+  ],
+});
+```
+
+**重要ポイント**:
+- `inlineDynamicImports: true`: すべてを単一ファイルにバンドル
+- `external`: 大きなライブラリやNode.js組み込みモジュールを外部化
+- `sourcemap: false`: 本番ビルドではソースマップを無効化
+
+### モノレポ向け設定
+
+```javascript
+import { defineConfig } from 'rollup';
+import alias from '@rollup/plugin-alias';
+import typescript from '@rollup/plugin-typescript';
+import nodeResolve from '@rollup/plugin-node-resolve';
+import commonjs from '@rollup/plugin-commonjs';
+import json from '@rollup/plugin-json';
+import path from 'path';
+
+export default defineConfig({
+  input: 'src/cli.ts',
+  output: {
+    file: 'dist/cli.js',
+    format: 'esm',
+    inlineDynamicImports: true,
+    sourcemap: false,
+  },
+  external: ['yaml'],
+  plugins: [
+    // 最初に alias でパス解決
+    alias({
+      entries: [
+        { 
+          find: '@internal/core', 
+          replacement: path.resolve('packages/core/dist/index.js') 
+        },
+        { 
+          find: '@internal/extract', 
+          replacement: path.resolve('packages/extract/dist/index.js') 
+        },
+      ],
+    }),
+    nodeResolve({ preferBuiltins: true }),
+    commonjs({ transformMixedEsModules: true }),
+    json(),
+    typescript({
+      tsconfig: './tsconfig.build.json',
+      outputToFilesystem: true,
+    }),
+  ],
+});
+```
+
+**重要ポイント**:
+- `alias` プラグインを**最初**に配置
+- workspace パッケージの `dist` を参照
+- `@internal/*` プレフィックスで内部パッケージを識別
+
+### ライブラリ向け設定（複数フォーマット）
+
+```javascript
+export default defineConfig([
+  // ESM 出力
+  {
+    input: 'src/index.ts',
+    output: {
+      file: 'dist/index.esm.js',
+      format: 'esm',
+      sourcemap: true,
+    },
+    external: ['react', 'lodash'],  // ピア依存は外部化
+    plugins: [
+      nodeResolve(),
+      commonjs(),
+      typescript({
+        tsconfig: './tsconfig.build.json',
+      }),
+    ],
+  },
+  // CJS 出力
+  {
+    input: 'src/index.ts',
+    output: {
+      file: 'dist/index.cjs.js',
+      format: 'cjs',
+      sourcemap: true,
+    },
+    external: ['react', 'lodash'],
+    plugins: [
+      nodeResolve(),
+      commonjs(),
+      typescript({
+        tsconfig: './tsconfig.build.json',
+      }),
+    ],
+  },
+]);
+```
+
+### プラグインの順序（重要）
+
+```javascript
+plugins: [
+  alias(),        // 1. パス解決を最初に
+  nodeResolve(),  // 2. 依存関係解決
+  commonjs(),     // 3. モジュール変換
+  json(),         // 4. JSON サポート
+  typescript(),   // 5. TypeScript コンパイル（最後）
+]
+```
+
+**理由**: プラグインは順番に処理されるため、依存関係解決 → 変換 → コンパイルの順序が重要
+
+### external 設定の指針
+
+```javascript
+// CLI ツールの場合
+external: [
+  'yaml',      // 大きなライブラリ
+  'glob',      // ランタイム依存
+  // Node.js 組み込みモジュールは自動的に外部化されるため不要
+]
+
+// ライブラリの場合
+external: [
+  'react',     // ピア依存関係
+  'lodash',    // ユーザーが既に持っている可能性が高い
+  /^@babel/,   // 特定のスコープパッケージ全体
+]
+```
+
+## TypeScript 設定
+
+### tsconfig.build.json の基本設定
+
+```json
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": false,
+    "removeComments": false,
+    "types": ["node"],
+    "module": "ESNext",
+    "target": "ES2020",
+    "moduleResolution": "Bundler",
+    "importHelpers": true,
+    "noEmitHelpers": false
+  },
+  "include": ["src/**/*"],
+  "exclude": [
+    "test/**/*",
+    "src/**/*.test.ts",
+    "src/**/*.spec.ts",
+    "**/*.test.ts",
+    "**/*.spec.ts"
+  ]
+}
+```
+
+### 重要な設定項目
+
+| オプション | 値 | 理由 |
+|-----------|-----|------|
+| `importHelpers` | `true` | tslib からヘルパー関数をインポート |
+| `noEmitHelpers` | `false` | ヘルパー関数の出力を許可 |
+| `moduleResolution` | `"Bundler"` | Rollup 用の解決戦略 |
+| `module` | `"ESNext"` | ES モジュール形式 |
+| `target` | `"ES2020"` | モダンな JavaScript ターゲット |
+| `sourceMap` | `false` | 本番ビルドでは無効化 |
+
+### モノレポでの tsconfig.json
+
+#### ルートプロジェクト
+
+```json
+{
+  "compilerOptions": {
+    "composite": true,
+    "declaration": true,
+    "importHelpers": true,
+    "noEmitHelpers": false
+  },
+  "references": []  // workspace パッケージは参照しない
+}
+```
+
+#### workspace パッケージ
+
+```json
+{
+  "compilerOptions": {
+    "composite": true,
+    "declaration": true,
+    "declarationMap": true,
+    "importHelpers": true,
+    "noEmitHelpers": false
+  },
+  "references": [
+    { "path": "../common" }  // 依存するパッケージを参照
+  ]
+}
+```
+
+## package.json 設定
+
+### 基本設定
+
+```json
+{
+  "name": "@scope/package-name",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}
+```
+
+### CLI ツールの場合
+
+```json
+{
+  "name": "@scope/cli-tool",
+  "version": "1.0.0",
+  "type": "module",
+  "bin": {
+    "my-cli": "dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}
+```
+
+**重要**: CLI のエントリーファイル（`dist/cli.js`）には shebang が必要
+
+```typescript
+#!/usr/bin/env node
+// CLI コード
+```
+
+### ビルドスクリプト
+
+```json
+{
+  "scripts": {
+    "build": "rollup -c",
+    "build:clean": "rm -rf dist && rollup -c",
+    "build:watch": "rollup -c -w",
+    "prepublishOnly": "npm run build:clean"
+  }
+}
+```
+
+### モノレポの場合
+
+```json
+{
+  "workspaces": [
+    "packages/core",
+    "packages/common"
+  ],
+  "scripts": {
+    "build": "npm run --ws build && tsc -p tsconfig.build.json",
+    "root:build": "npm run build && if [ \"$NODE_ENV\" != \"test\" ]; then rollup -c && chmod +x dist/cli.js; fi",
+    "build:pkg:clean": "npm run --ws clean",
+    "clean": "npm run build:pkg:clean && rm -rf dist",
+    "prepublishOnly": "npm run root:build"
+  }
+}
+```
+
+**ビルド順序**:
+1. `npm run --ws build`: 各パッケージのビルド
+2. `tsc -p tsconfig.build.json`: ルートプロジェクトのコンパイル
+3. `rollup -c`: バンドル生成
+4. `chmod +x dist/cli.js`: 実行権限付与（CLI の場合）
+
+## ビルドプロセス
+
+### 標準的なビルドフロー
+
+```mermaid
+graph TD
+    A[workspace ビルド] --> B[ルート TypeScript コンパイル]
+    B --> C[Rollup バンドル]
+    C --> D[実行権限付与]
+    D --> E[配布物完成]
+```
+
+### 実行コマンド
+
+```bash
+# 開発時のビルド
+npm run build
+
+# クリーンビルド
+npm run build:clean
+
+# watch モード（開発時）
+npm run build:watch
+
+# 本番ビルド（公開前）
+npm run prepublishOnly
+```
+
+### CI/CD での実行
+
+```yaml
+# GitHub Actions の例
+- name: Install dependencies
+  run: npm ci
+
+- name: Build project
+  run: npm run build:clean
+
+- name: Verify CLI executable
+  run: |
+    chmod +x dist/cli.js
+    ./dist/cli.js --help
+```
+
+### 環境別の考慮事項
+
+#### 開発環境（`NODE_ENV=development`）
+
+```javascript
+const isDev = process.env.NODE_ENV === 'development';
+
+export default defineConfig({
+  output: {
+    sourcemap: isDev,  // 開発時のみソースマップ
+  },
+  plugins: [
+    typescript({
+      sourceMap: isDev,
+      inlineSources: isDev,
+    }),
+  ],
+});
+```
+
+#### テスト環境（`NODE_ENV=test`）
+
+```json
+{
+  "scripts": {
+    "root:build": "npm run build && if [ \"$NODE_ENV\" != \"test\" ]; then rollup -c; fi"
+  }
+}
+```
+
+**理由**: テスト時は Rollup バンドルをスキップして高速化
+
+## 配布物の品質確認
+
+### 必須チェック項目
+
+#### 1. パッケージ内容の確認
+
+```bash
+# ドライラン実行（ファイル一覧表示）
+npm pack --dry-run
+
+# 実際にパッケージ化
+npm pack
+
+# 内容確認
+tar -tzf package-name-1.0.0.tgz
+```
+
+#### 2. .npmignore の設定
+
+```
+# 開発用ファイル
+src/
+test/
+*.test.ts
+*.spec.ts
+
+# 設定ファイル
+tsconfig*.json
+rollup.config.mjs
+.eslintrc*
+.prettierrc*
+
+# ドキュメント（README.md は含める）
+docs/
+.github/
+
+# ビルドキャッシュ
+*.tsbuildinfo
+.cache/
+```
+
+#### 3. files フィールドの確認
+
+```json
+{
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ]
+}
+```
+
+**ベストプラクティス**: `.npmignore` より `files` フィールドを推奨（明示的で安全）
+
+### 確認タイミング
+
+- ✅ 機能追加・リファクタリング後
+- ✅ リリース前（必須）
+- ✅ コミット前（推奨）
+
+### バンドルサイズの確認
+
+```bash
+# ファイルサイズ確認
+ls -lh dist/cli.js
+
+# 依存関係の可視化（オプション）
+npx rollup-plugin-visualizer
+```
+
+## トラブルシューティング
+
+### よくある問題と解決方法
+
+#### 1. tslib エラー
+
+**症状**:
+```text
+RollupError: [plugin typescript] @rollup/plugin-typescript: Could not find module 'tslib'
+```
+
+**原因**: tslib パッケージ未インストール
+
+**解決**:
+```bash
+npm install --save-dev tslib
+```
+
+#### 2. モジュール解決エラー
+
+**症状**:
+```text
+Error: Could not resolve '@internal/core' from src/cli.ts
+```
+
+**原因**: alias 設定または build 順序の問題
+
+**解決**:
+```bash
+# 1. workspace パッケージが先にビルドされているか確認
+npm run --ws build
+
+# 2. alias の path 設定を確認
+# rollup.config.mjs で path.resolve() を使用
+```
+
+#### 3. shebang 重複エラー
+
+**症状**:
+```javascript
+#!/usr/bin/env node
+#!/usr/bin/env node
+// コード
+```
+
+**原因**: rollup.config.mjs の `banner` とソースファイルの shebang が重複
+
+**解決**:
+```javascript
+// rollup.config.mjs から banner を削除
+export default defineConfig({
+  output: {
+    // banner: '#!/usr/bin/env node',  // ← 削除
+  }
+});
+
+// ソースファイル（src/cli.ts）側で定義
+#!/usr/bin/env node
+```
+
+#### 4. 実行権限エラー
+
+**症状**:
+```text
+Permission denied: ./dist/cli.js
+```
+
+**原因**: 生成されたファイルに実行権限がない
+
+**解決**:
+```bash
+chmod +x dist/cli.js
+```
+
+または package.json で自動化:
+```json
+{
+  "scripts": {
+    "root:build": "... && chmod +x dist/cli.js"
+  }
+}
+```
+
+#### 5. CommonJS と ES モジュールの混在問題
+
+**症状**:
+```text
+[!] (plugin commonjs) TypeError: Cannot read property 'xxx' of undefined
+```
+
+**原因**: CommonJS モジュールの変換が適切に行われていない
+
+**解決**:
+```javascript
+commonjs({
+  transformMixedEsModules: true,  // 混在モジュールの変換を有効化
+})
+```
+
+#### 6. 外部依存関係の処理エラー
+
+**症状**:
+```text
+Module 'yaml' not found in bundle
+```
+
+**解決**:
+```javascript
+// オプション 1: 外部化
+external: ['yaml'],
+
+// オプション 2: バンドルに含める（external から削除）
+external: [],  // yaml はバンドルされる
+```
+
+### デバッグ手順
+
+#### 段階的ビルド確認
+
+```bash
+# 1. パッケージビルド確認
+npm run --ws build
+
+# 2. ルートコンパイル確認
+tsc -p tsconfig.build.json
+
+# 3. Rollup バンドル確認
+rollup -c
+
+# 4. 成果物確認
+ls -la dist/
+```
+
+#### 依存関係確認
+
+```bash
+# tslib インストール確認
+npm list tslib
+
+# workspace 依存関係確認
+npm list --workspaces
+
+# 全体の依存関係ツリー
+npm list
+```
+
+## ベストプラクティス
+
+### 1. プラグインの順序を守る
+
+```javascript
+plugins: [
+  alias(),        // パス解決を最初に
+  nodeResolve(),  // 依存関係解決
+  commonjs(),     // モジュール変換
+  json(),         // JSON サポート
+  typescript(),   // TypeScript コンパイル（最後）
+]
+```
+
+### 2. 外部依存関係の適切な管理
+
+```javascript
+// CLI ツール: ランタイム依存のみ外部化
+external: ['yaml', 'glob'],
+
+// ライブラリ: ピア依存関係を外部化
+external: ['react', 'lodash'],
+```
+
+### 3. 出力フォーマットの選択
+
+```javascript
+// CLI ツール: 単一フォーマット
+output: {
+  file: 'dist/cli.js',
+  format: 'esm',
+}
+
+// ライブラリ: 複数フォーマット
+output: [
+  { file: 'dist/index.esm.js', format: 'esm' },
+  { file: 'dist/index.cjs.js', format: 'cjs' },
+]
+```
+
+### 4. Tree-shaking の最大化
+
+```typescript
+// ❌ 全体インポート
+import * as utils from './utils';
+
+// ✅ 必要な部分のみインポート
+import { specificFunction } from './utils';
+```
+
+### 5. ビルドキャッシュの活用
+
+```json
+{
+  "compilerOptions": {
+    "incremental": true,
+    "tsBuildInfoFile": ".tsbuildinfo"
+  }
+}
+```
+
+### 6. 環境変数による制御
+
+```javascript
+const isDev = process.env.NODE_ENV === 'development';
+
+export default defineConfig({
+  output: {
+    sourcemap: isDev,
+  },
+  treeshake: isDev ? false : {
+    moduleSideEffects: false,
+  },
+});
+```
+
+### 7. モノレポでのビルド順序管理
+
+```json
+{
+  "scripts": {
+    "build": "npm run --ws build && tsc && rollup -c",
+    "build:watch": "npm run --ws build:watch & rollup -c -w"
+  }
+}
+```
+
+### 8. 配布物の最終確認
+
+```bash
+# リリース前チェックリスト
+npm run build:clean       # クリーンビルド
+npm test                  # テスト実行
+npm pack --dry-run        # パッケージ内容確認
+npm run prepublishOnly    # 公開前処理
+```
+
+## まとめ
+
+### Rollup を使うべき場面
+
+1. **CLI ツール開発**: 単一ファイルの実行可能ファイル生成
+2. **ライブラリ開発**: 小さなバンドルサイズと複数フォーマット対応
+3. **モノレポ**: 複数パッケージの統合バンドル
+4. **TypeScript プロジェクト**: tslib との連携による最適化
+
+### 重要なチェックポイント
+
+- ✅ tslib のインストール（ルートと各パッケージ）
+- ✅ プラグインの順序（alias → nodeResolve → commonjs → json → typescript）
+- ✅ external 設定（大きなライブラリは外部化）
+- ✅ TypeScript 設定（`importHelpers: true`, `noEmitHelpers: false`）
+- ✅ package.json の `files` フィールド
+- ✅ `npm pack --dry-run` での配布物確認
+- ✅ CLI の場合は shebang と実行権限
+
+### 参考リンク
+
+- [Rollup 公式ドキュメント](https://rollupjs.org/)
+- [@rollup/plugin-typescript](https://github.com/rollup/plugins/tree/master/packages/typescript)
+- [tslib](https://github.com/Microsoft/tslib)