turborepo-monorepo

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=...  # Verify task execution order
   

タスクの設定

1. turbo.json でタスクを設定する：

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

2. タスクを実行する：

   turbo run build                      # All packages
   turbo run lint test build           # Multiple tasks
   turbo run build --filter=web       # Specific package
   

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

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

4. コミット前に検証する：

   turbo run build --dry-run  # Check task order and affected packages
   

フレームワークとの統合

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: Review output to confirm only expected packages will build
   
   - 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: Confirm cache hits for unchanged packages
   

2. リモートキャッシュのセットアップ：

   # Login to Vercel
   npx turbo login
   
   # Link repository
   npx turbo link
   

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

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

プロパティ	説明	例
dependsOn	先に完了している必要があるタスク	["^build"] - 依存先を先に実行
outputs	キャッシュするファイル／フォルダー	["dist/**"]
inputs	キャッシュハッシュの対象となるファイル	["src/**/*.ts"]
env	ハッシュに影響する環境変数	["DATABASE_URL"]
cache	キャッシュを有効／無効にする	true または false
persistent	長時間実行するタスク	開発サーバーの場合は 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

# Add Next.js app
pnpm add next react react-dom -F apps/web

# Add 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：キャッシュの問題をデバッグする

入力： 「キャッシュミスが発生するのはなぜですか？」

# Dry run to see what would be executed
turbo run build --dry-run --filter=web

# Show hash inputs
turbo run build --force --filter=web

制約と警告

• Turborepo には Node.js 18+ が必要です
• ルートの package.json に package manager フィールドが必要です
• キャッシュを機能させるには outputs の指定が必要です
• 永続タスクに依存先を設定することはできません
• 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