Turborepo モノレポ

概要

Turborepo モノレポ管理のガイダンスを提供します。ワークスペース作成、turbo.json タスク設定、Next.js/NestJS の統合、テストパイプライン（Vitest/Jest）、CI/CD セットアップ、およびビルドパフォーマンスの最適化に対応しています。

使用する場合

• Turborepo ワークスペースの作成または初期化
• 依存関係と出力を持つ turbo.json タスクの設定
• モノレポ構造での Next.js/NestJS アプリの設定
• Vitest/Jest テストパイプラインの設定
• CI/CD ワークフローの構築（GitHub Actions、GitLab CI）
• Vercel Remote Cache によるリモートキャッシング実装
• ビルド時間とキャッシュ命中率の最適化
• タスク依存関係またはキャッシュの問題をデバッグ
• 他のモノレポツールから Turborepo への移行

手順

ワークスペース作成

1. 新しいワークスペースの作成:

   pnpm create turbo@latest my-workspace
   cd my-workspace
   

2. 既存プロジェクトでの初期化:

   pnpm add -D -w turbo
   

3. ルートで turbo.json を作成（最小設定）:

   {
     "$schema": "https://turborepo.dev/schema.json",
     "pipeline": {
       "build": { "dependsOn": ["^build"], "outputs": ["dist/**", ".next/**"] },
       "lint": { "outputs": [] },
       "test": { "dependsOn": ["build"], "outputs": ["coverage/**"] }
     }
   }
   

4. ルートの package.json にスクリプトを追加:

   { "scripts": { "build": "turbo run build", "dev": "turbo run dev", "lint": "turbo run lint", "test": "turbo run test", "clean": "turbo run clean" } }
   

5. CI 前にタスクグラフを検証:

   turbo run build --dry-run --filter=...  # タスク実行順序を確認
   

タスク設定

1. turbo.json でタスクを設定:

   { "pipeline": { "build": { "dependsOn": ["^build"], "outputs": ["dist/**"] }, "test": { "dependsOn": ["build"], "outputs": ["coverage/**"] }, "lint": { "outputs": [] } } }
   

2. タスクを実行:

   turbo run build                      # すべてのパッケージ
   turbo run lint test build           # 複数タスク
   turbo run build --filter=web       # 特定パッケージ
   

3. 並列型チェック（キャッシュの問題を避けるためトランジットノードを使用）:

   { "pipeline": { "transit": { "dependsOn": ["^transit"] }, "typecheck": { "dependsOn": ["transit"] } } }
   

4. コミット前に検証:

   turbo run build --dry-run  # タスク順序と影響を受けるパッケージを確認
   

フレームワーク統合

Next.js: ".next/**" を出力し、["NEXT_PUBLIC_*"] 環境変数を使用 - references/nextjs-config.md を参照

NestJS: "dist/**" を出力、cache: false, persistent: true で開発タスク - references/nestjs-config.md を参照

テスト設定

1. Vitest 設定:

   {
     "pipeline": {
       "test": {
         "outputs": [],
         "inputs": ["$TURBO_DEFAULT$", "vitest.config.ts"]
       },
       "test:watch": {
         "cache": false,
         "persistent": true
       }
     }
   }
   

2. 影響を受けたテストを実行:

   turbo run test --filter=[HEAD^]
   

   完全なテスト設定については references/testing-config.md を参照してください。

パッケージ設定

1. パッケージ固有の turbo.json を作成:

   {
     "extends": ["//"],
     "tasks": {
       "build": {
         "outputs": ["$TURBO_EXTENDS$", ".next/**"]
       }
     }
   }
   

   詳細なパッケージ設定パターンについては references/package-configs.md を参照してください。

CI/CD 設定

1. 検証チェックポイント付きの GitHub Actions:

   - name: Install dependencies
     run: pnpm install
   
   - name: Validate affected packages (dry-run)
     run: pnpm turbo run build --filter=[HEAD^] --dry-run
     # VALIDATE: 出力を確認して、想定されたパッケージのみがビルドされることを確認
   
   - name: Run tests
     run: pnpm run test --filter=[HEAD^]
   
   - name: Build affected packages
     run: pnpm run build --filter=[HEAD^]
   
   - name: Verify cache hits
     run: pnpm turbo run build --filter=[HEAD^] --dry-run | grep "Cache"
     # VALIDATE: 変更されていないパッケージのキャッシュ命中を確認
   

2. リモートキャッシュ設定:

   # Vercel にログイン
   npx turbo login
   
   # リポジトリをリンク
   npx turbo link
   

   完全な CI/CD セットアップ例については references/ci-cd.md を参照してください。

タスク プロパティ リファレンス

プロパティ	説明	例
dependsOn	先に完了する必要があるタスク	["^build"] - 依存関係を優先
outputs	キャッシュするファイル/フォルダ	["dist/**"]
inputs	キャッシュハッシュ用ファイル	["src/**/*.ts"]
env	ハッシュに影響する環境変数	["DATABASE_URL"]
cache	キャッシングの有効/無効	true または false
persistent	長時間実行タスク	dev サーバー用 true
outputLogs	ログの詳細度	"full"、"new-only"、"errors-only"

依存関係パターン

• ^task - 依存関係内のタスクを最初に実行（トポロジカル順序）
• task - 同じパッケージ内のタスクを最初に実行
• package#task - 特定パッケージのタスクを実行

フィルター構文

フィルター	説明
web	web パッケージのみ
web...	web + すべての依存関係
...web	web + すべての依存元
...web...	web + 依存関係 + 依存元
[HEAD^]	前回コミット以降の変更パッケージ
./apps/*	apps/ 内のすべてのパッケージ

ベストプラクティス

パフォーマンス最適化

1. 特定の出力を使用 - 必要な部分のみキャッシュ
2. 入力を微調整 - 出力に影響しないファイルを除外
3. トランジットノード - 並列型チェックを有効化
4. リモートキャッシュ - チーム/CI 全体でキャッシュを共有
5. パッケージ設定 - パッケージごとの動作をカスタマイズ

キャッシング戦略

{
  "pipeline": {
    "build": {
      "outputs": ["dist/**"],
      "inputs": ["$TURBO_DEFAULT$", "!README.md", "!**/*.md"]
    }
  }
}

タスク構成

• 独立タスク - dependsOn なし: lint、format、spellcheck
• ビルドタスク - dependsOn: ["^build"]: build、compile
• テストタスク - dependsOn: ["build"]: test、e2e
• 開発タスク - cache: false, persistent: true: dev、watch

よくある問題

タスクが順序通りに実行されない

問題: タスクが間違った順序で実行される

解決方法: dependsOn 設定を確認

{
  "build": {
    "dependsOn": ["^build"]
  }
}

変更されていないファイルでキャッシュミスが発生

問題: キャッシュが予期せず無効化される

解決方法: globalDependencies と inputs を確認

{
  "globalDependencies": ["tsconfig.json"],
  "pipeline": {
    "build": {
      "inputs": ["$TURBO_DEFAULT$", "!*.md"]
    }
  }
}

キャッシュ命中後の型エラー

問題: キャッシュにより TypeScript エラーが検出されない

解決方法: 型チェック用にトランジットノードを使用

{
  "transit": { "dependsOn": ["^transit"] },
  "typecheck": { "dependsOn": ["transit"] }
}

例

例 1: 新しいワークスペースを作成

入力: "Next.js と NestJS を含む Turborepo を作成"

pnpm create turbo@latest my-workspace
cd my-workspace

# Next.js アプリを追加
pnpm add next react react-dom -F apps/web

# NestJS API を追加
pnpm add @nestjs/core @nestjs/common -F apps/api

例 2: テストパイプラインを設定

入力: "すべてのパッケージで Vitest をセットアップ"

{
  "pipeline": {
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"],
      "inputs": ["$TURBO_DEFAULT$", "vitest.config.ts"]
    },
    "test:watch": {
      "cache": false,
      "persistent": true
    }
  }
}

例 3: CI で影響を受けたテストを実行

入力: "CI で変更されたパッケージのみテスト"

pnpm run test --filter=[HEAD^]

例 4: キャッシュの問題をデバッグ

入力: "キャッシュミスの原因を調査"

# ドライランで実行内容を確認
turbo run build --dry-run --filter=web

# ハッシュ入力を表示
turbo run build --force --filter=web

制約と警告

• Node.js 18+ が Turborepo に必須
• パッケージマネージャーフィールド が root の package.json で必須
• 出力は必ず指定 してキャッシング機能を有効化
• 持続的なタスク は依存元を持つことができません
• Windows: WSL または Git Bash を推奨
• リモートキャッシュ は Vercel アカウントまたは自己ホストソリューションが必要
• 大規模モノレポ は concurrency 設定の増加が必要な場合があります

リファレンスファイル

特定のトピックに関する詳細なガイダンスについては、以下を参照してください:

トピック	リファレンスファイル
turbo.json テンプレート	references/turbo.json
Next.js 統合	references/nextjs-config.md
NestJS 統合	references/nestjs-config.md
Vitest/Jest/Playwright	references/testing-config.md
GitHub/CircleCI/GitLab CI	references/ci-cd.md
パッケージ設定	references/package-configs.md