turborepo

Turborepo スキル

Turborepo を使用した JavaScript および TypeScript のモノレポ向けビルドシステムのガイダンスです。

コアとなるルール

1. ルートタスクではなく、パッケージタスクを作成します。
2. タスクの動作は turbo.json に登録します。
3. ルートの package.json から turbo run <task> を呼び出します。
4. turbo <task> は対話型の単発ターミナルコマンドにのみ使用し、コミットするコードでは使用しません。
5. dependsOn: ["^build"] で実際のパッケージ間の依存関係を解決できるよう、ワークスペースの依存関係を package.json に宣言します。

基本パターン

// apps/web/package.json
{
  "scripts": {
    "build": "next build",
    "lint": "eslint .",
    "test": "vitest"
  }
}

// turbo.json
{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
    },
    "lint": {},
    "test": {
      "dependsOn": ["build"]
    }
  }
}

// root package.json
{
  "scripts": {
    "build": "turbo run build",
    "lint": "turbo run lint",
    "test": "turbo run test"
  }
}

クイックルーティング

タスクに必要なリファレンスファイルのみを読みます。

必要な項目	読むファイル
タスク定義、dependsOn、outputs、persistent、パッケージのオーバーライド	references/configuration/RULE.md、references/configuration/tasks.md
グローバルオプション、デーモン、cacheDir、環境モード	references/configuration/global-options.md
キャッシュミスまたはリモートキャッシュ	references/caching/RULE.md、references/caching/gotchas.md、references/caching/remote-cache.md
環境変数、.env、strict モードと loose モード	references/environment/RULE.md、references/environment/modes.md、references/environment/gotchas.md
--affected、--filter、パッケージの選択	references/filtering/RULE.md、references/filtering/patterns.md
CI、GitHub Actions、Vercel、turbo-ignore	references/ci/RULE.md、references/ci/github-actions.md、references/ci/vercel.md、references/ci/patterns.md、references/cli/commands.md
リポジトリ構造、パッケージの作成、依存関係の管理	references/best-practices/RULE.md、references/best-practices/structure.md、references/best-practices/packages.md、references/best-practices/dependencies.md
ウォッチモードと長時間実行する開発タスク	references/watch/RULE.md、references/configuration/tasks.md
パッケージ境界と分離	references/boundaries/RULE.md

判断ツリー

タスクを設定する

Configure a task?
├─ Define dependencies or outputs → configuration/tasks.md
├─ Handle environment variables → environment/RULE.md
├─ Set package-specific overrides → configuration/RULE.md#package-configurations
├─ Add persistent/watch behavior → configuration/tasks.md + watch/RULE.md
└─ Tune global options → configuration/global-options.md

キャッシュをデバッグする

Cache issue?
├─ Outputs not restored → add or fix `outputs`
├─ Unexpected misses → caching/gotchas.md
├─ Remote cache issue → caching/remote-cache.md
└─ Env or .env drift → environment/gotchas.md

変更された項目のみを実行する

Need changed packages only?
├─ Default path → `turbo run <task> --affected`
├─ Custom comparison base → add `--affected-base=...`
└─ Custom package selection → filtering/RULE.md + filtering/patterns.md

CI を設定する

CI setup?
├─ GitHub Actions → ci/github-actions.md
├─ Vercel deployment → ci/vercel.md
├─ Remote cache in CI → caching/remote-cache.md
└─ Skip unchanged work → ci/patterns.md + cli/commands.md

モノレポを構成する

Repo/package structure?
├─ apps/ vs packages/ layout → best-practices/RULE.md
├─ Create internal package → best-practices/packages.md
├─ Workspace dependency management → best-practices/dependencies.md
└─ Enforce package boundaries → boundaries/RULE.md

重大なアンチパターン

• Turborepo を完全に迂回するルートスクリプト。ルートスクリプトでは、アプリ固有のタスクロジックを埋め込むのではなく、turbo run を呼び出します。
• package.json、CI、スクリプトにコミットされた turbo build または turbo lint コマンド。コミットするコードでは turbo run ... を使用します。
• ワークスペースの依存関係を宣言して ^build を使用する代わりに、兄弟パッケージをコンパイルする手動の prebuild チェーン。
• ファイルを書き出すタスクに outputs がないこと。タスクをキャッシュ可能と判断する前に、実際のスクリプトを確認します。
• env から環境変数が漏れている、または inputs から .env ファイルが漏れているために、古いキャッシュがヒットすること。
• モノレポのルートレベルに .env ファイルを置くこと。パッケージ間に見えにくい結合を生みます。
• パッケージ API を通じてインポートせず、相対インポートやファイルの階層をたどってパッケージ境界を越えること。
• パッケージごとのオーバーライドでルートの turbo.json を煩雑にすること。代わりにパッケージごとの turbo.json ファイルを使用します。

詳しい例については、以下を参照してください。

• references/configuration/gotchas.md
• references/caching/gotchas.md
• references/environment/gotchas.md
• references/best-practices/structure.md
• references/best-practices/packages.md

よくある設定

標準的なビルドと開発

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

キャッシュを正しく無効化しながら並列タスクを実行するための中継ノード

{
  "tasks": {
    "transit": {
      "dependsOn": ["^transit"]
    },
    "lint": {
      "dependsOn": ["transit"]
    }
  }
}

タスクを並列実行できる一方で、依存関係にあるソースの変更をキャッシュ無効化に反映する必要がある場合に使用します。

ウォッチモードのパターン

ファイル変更の監視ループには turbo watch を使用し、スクリプト内で即席に作成した turbo run ... --watch パターンは使用しません。persistent、interruptible、または with を設定する前に、references/watch/RULE.md を読んでください。

検証チェックリスト

• コードまたは CI でコミットされているすべてのコマンドは、turbo run ... を使用しています。
• タスクはパッケージのスクリプトに記述し、ルートのスクリプトは委譲のみを行います。
• dependsOn は実際の依存関係に一致しています。上流のパッケージには ^task、同じパッケージ内の前提タスクには task を使用します。
• キャッシュ可能なファイル生成タスクでは、outputs を宣言しています。
• 関連する環境変数は env または globalEnv に記述しています。
• 関連する .env ファイルは inputs に含めています。
• ワークスペースのパッケージ間のインポートには、相対ソースパスではなくパッケージ名を使用しています。
• CI では、デフォルトですべてを再ビルドするのではなく、適切な場合に --affected またはフィルターを使用しています。

参照ドキュメント

Turborepo の公式ドキュメント（ライブラリ v2.9.7-canary.12）に基づいています：apps/docs/content/docs/ — https://turborepo.dev/docs