shared-monorepo-turborepo

Turborepo によるモノレポのオーケストレーション

クイックガイド： モノレポのオーケストレーションには Turborepo 2.x を使用します。依存関係の順序を考慮したタスクパイプラインを設定します。ローカルキャッシュとリモートキャッシュにより、大幅な高速化を実現します。パッケージのリンクにはワークスペースを使用します。依存関係のバージョンを統一するには Syncpack を使用します。内部パッケージには @repo/* の命名規則、明示的な exports フィールド、workspace:* プロトコルを使用します。

---

<critical_requirements>

重要：このスキルを使用する前に

すべてのコードは CLAUDE.md のプロジェクト規約に従う必要があります（kebab-case、名前付きエクスポート、インポート順序、import type、名前付き定数）

（トポロジカル順序を確実にするため、turbo.json で dependsOn: ["^build"] を使用してタスクの依存関係を必ず定義してください）

（適切なキャッシュ無効化のため、turbo.json のタスクの env 配列ですべての環境変数を必ず宣言してください）

（開発サーバーやコード生成など、副作用のあるタスクには必ず cache: false を設定してください）

（内部パッケージの依存関係には必ず workspace:* プロトコルを使用してください）

（すべての内部パッケージには必ず @repo/* の命名規則を使用してください）

（package.json には必ず明示的な exports フィールドを定義し、内部パスのインポートは決して許可しないでください）

（コンポーネントパッケージでは React を dependencies ではなく、必ず peerDependencies に指定してください）

</critical_requirements>

---

自動検出： Turborepo の設定、turbo.json、モノレポのセットアップ、ワークスペース、Bun ワークスペース、Syncpack、タスクパイプライン、@repo/* パッケージ、package.json の exports、ワークスペースの依存関係、共有設定

使用する場面：

• Turborepo のタスクパイプラインとキャッシュ戦略を設定するとき
• モノレポのパッケージリンク用にワークスペースをセットアップするとき
• チームや CI 間でキャッシュを共有するためにリモートキャッシュを有効にするとき
• ワークスペース内のパッケージ間で依存関係のバージョンを統一するとき
• packages/ に新しい内部パッケージを作成するとき
• ツリーシェイキング用に package.json の exports を設定するとき
• 共有設定パッケージ（@repo/eslint-config、@repo/typescript-config）をセットアップするとき

使用しない場面：

• 単一のアプリケーションプロジェクト（標準のビルドツールを直接使用してください）
• 共有パッケージのないプロジェクト（モノレポのメリットがありません）
• セットアップのオーバーヘッドがキャッシュによるメリットを上回る小規模なプロジェクト
• モノレポよりポリレポアーキテクチャが適している場合
• すでに Nx または Lerna を使用しているプロジェクト（モノレポツールを併用しないでください）
• 共有しないアプリ固有のコード（アプリのディレクトリ内に配置してください）

対象となる主なパターン：

• Turborepo 2.x のタスクパイプライン（dependsOn、outputs、inputs、cache）
• ローカルキャッシュとリモートキャッシュの戦略
• パッケージリンク用のワークスペース
• 依存関係のバージョン統一に使う Syncpack
• turbo.json での環境変数の処理
• パッケージ構成と @repo/* の命名規則
• ツリーシェイキング用の package.json exports
• 名前付きエクスポートとバレルファイルのパターン
• workspace プロトコルによる内部依存関係

詳細リソース：

• コード例については、examples/core.md を参照してください（必ずここから始めてください）
  • examples/caching.md - リモートキャッシュ、CI/CD 連携
  • examples/workspaces.md - ワークスペースプロトコル、Syncpack、依存関係の境界
  • examples/packages.md - 内部パッケージの規約、exports、パッケージの作成
• 判断基準とアンチパターンについては、reference.md を参照してください

---

基本方針

Turborepo は、JavaScript/TypeScript のモノレポ向けに設計された高性能ビルドシステムです。インテリジェントなタスクスケジューリング、キャッシュ、リモートキャッシュ共有により、ビルド時間を大幅に短縮します。ワークスペースと組み合わせることで、依存関係の自動リンクを備えた効率的なパッケージ管理を実現します。

---

基本パターン

パターン 1：依存関係の順序を考慮した Turborepo タスクパイプライン

turbo.json でタスクの依存関係とキャッシュの動作を定義し、インテリジェントなビルドのオーケストレーションとキャッシュを実現します。

#### 主な概念

• dependsOn: ["^build"] - 依存タスクを先に実行します（トポロジカル順）
• outputs - キャッシュするファイルを定義します
• inputs - キャッシュ無効化のトリガーとなるファイルを指定します
• cache: false - 副作用のあるタスクのキャッシュを無効にします
• persistent: true - 開発サーバーを起動したままにします

最小限の例

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "env": ["DATABASE_URL", "NODE_ENV"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
    },
    "dev": { "cache": false, "persistent": true }
  }
}

ポイント： dependsOn: ["^build"] によりトポロジカル順で実行され、env でキャッシュ無効化の対象となる変数を宣言し、副作用のあるタスクには cache: false を指定します。

適切な例と不適切な例の詳しい比較については、examples/core.md をご覧ください。

---

パターン 2：キャッシュ戦略

Turborepo のキャッシュシステムは、入力に変更がない場合に以前のタスク出力を再利用することで、ビルドを大幅に高速化します。

キャッシュされるもの

• ビルド出力（dist/、.next/、フレームワーク固有のディレクトリ）
• テスト結果（cache: true の場合）
• Lint の結果

キャッシュされないもの

• 開発サーバー（cache: false）
• コード生成（ファイルを生成するため cache: false）
• 副作用のあるタスク

キャッシュ無効化のトリガー

• ソースファイルの変更
• 依存関係の変更
• 環境変数の変更（env 配列に含まれている場合）
• グローバル依存関係の変更（.env、tsconfig.json）

セットアップ： Vercel アカウント（またはセルフホスト可能なキャッシュ）をリンクし、TURBO_TOKEN と TURBO_TEAM の環境変数を設定して、リモートキャッシュの共有を有効にします。

リモートキャッシュの設定と CI 連携の例については、examples/caching.md をご覧ください。

---

パターン 3：パッケージ管理のためのワークスペース

ワークスペースを設定して、モノレポのパッケージ間でパッケージのリンクと依存関係の共有を有効にします。

主な概念

• ルートの package.json で "workspaces": ["apps/*", "packages/*"] を宣言します
• 内部依存関係には "@repo/ui": "workspace:*" プロトコルを使用して、自動リンクを有効にします
• 標準的な構成では、デプロイ可能なアプリに apps/、共有コードに packages/ を使用します

適切な例と不適切な例の詳しい比較、および syncpack の設定については、examples/workspaces.md をご覧ください。

---

パフォーマンスの最適化

キャッシュヒットの指標：

• 初回ビルド：約45秒（5パッケージ、キャッシュなし）
• キャッシュ済みビルド：約1秒（ローカルキャッシュにより97％高速化）
• 影響範囲に限定したビルド：約12秒（73％高速化、変更されたパッケージのみ再ビルド）
• チーム全体の削減効果：リモートキャッシュを有効にすると、週あたり数時間

最適化戦略：

• すべてのパッケージに影響するファイル（.env、tsconfig.json）には globalDependencies を設定し、不要なキャッシュ無効化を防ぎます
• inputs 配列を使用し、タスクごとにキャッシュ無効化のトリガーを細かく調整します
• リモートキャッシュを有効にし、チームや CI 間でアーティファクトを共有します
• 影響範囲の検出と --filter（--filter=...[HEAD^]）を使用し、変更されたパッケージのタスクのみを実行します
• outputs を慎重に設定し、キャッシュディレクトリを除外します（例：!.next/cache/**）

キャッシュを強制的にバイパスする：

# Ignore cache when needed
bun run build --force

# Only build affected packages
bun run build --filter=...[HEAD^1]

---

<decision_framework>

判断フレームワーク

New code? → Shared across 2+ apps? → packages/ (else keep in app)
Monorepo? → Builds > 30s or caching matters? → Use Turborepo

包括的な判断ツリーとパッケージ作成基準については、reference.md をご覧ください。

</decision_framework>

---

<red_flags>

重大な問題

優先度の高い問題：

• ビルドタスクに dependsOn: ["^build"] がない（トポロジカル順序が崩れます）
• turbo.json に env 配列がない（環境間でキャッシュミスが発生します）
• 開発サーバーやコード生成をキャッシュする（誤った出力が再利用されます）
• ライブラリパッケージでデフォルトエクスポートを使う（ツリーシェイキングが機能しなくなります）
• package.json に exports フィールドがない（内部パスのインポートが可能になります）

よくある間違い：

• 内部依存関係に workspace:* を使わず、バージョンをハードコードする
• React を peerDependencies ではなく dependencies に指定する
• あらゆるものを再エクスポートする巨大なバレルファイルを作る（ツリーシェイキングの効果がなくなります）
• 影響範囲の検出に --filter=...[HEAD^] を使わず、テストスイート全体を実行する

注意点：

• dependsOn: ["^task"] は依存パッケージのタスクを実行し、dependsOn: ["task"] は同じパッケージのタスクを実行します
• --filter=...[HEAD^] を使う場合、GitHub Actions で fetch-depth: 2 が必要です
• 出力からキャッシュディレクトリを除外します：!.next/cache/**

アンチパターンとチェックリストの詳細については、reference.md を参照してください。

</red_flags>

---

<critical_reminders>

重要な注意事項

すべてのコードは CLAUDE.md のプロジェクト規約に従う必要があります

（トポロジカル順序を確保するため、turbo.json で dependsOn: ["^build"] を使ってタスクの依存関係を必ず定義してください）

（キャッシュを適切に無効化するため、turbo.json のタスクの env 配列にすべての環境変数を必ず宣言してください）

（開発サーバーやコード生成など、副作用のあるタスクには cache: false を必ず設定してください）

（内部パッケージの依存関係には、必ず workspace:* プロトコルを使用してください）

（すべての内部パッケージには、必ず @repo/* の命名規則を使用してください）

（package.json には明示的な exports フィールドを必ず定義してください。内部パスのインポートは許可しないでください）

（コンポーネントパッケージでは、React を dependencies ではなく peerDependencies に必ず指定してください）

これらのルールに従わないと、ビルドの不整合、キャッシュミス、依存関係の解決エラー、ツリーシェイキングの失敗が発生します。

</critical_reminders>