turborepo

Turborepo

概要

JavaScript/TypeScript モノレポ向けのビルドシステムです。タスクの出力をキャッシュし、依存関係グラフに基づいてタスクを並列実行します。常にルートタスクではなくパッケージタスクを作成し、スクリプトでは turbo run を使用して、実行順序の管理は dependsOn に任せます。設定には turbo.json（コメントを使う場合は turbo.jsonc）を使用します。

使用するケース： モノレポのタスクオーケストレーション、ビルドキャッシュ、CI の最適化、ワークスペースの依存関係管理、パッケージ境界の適用。

使用しないケース： 単一パッケージのプロジェクト、JavaScript 以外のモノレポ、ビルド手順のないプロジェクト。

クイックリファレンス

パターン	構文	ポイント
スキーマ	"$schema": "https://turborepo.dev/schema.json"	turbo.json に必ず含める
依存関係のビルド	"dependsOn": ["^build"]	先に依存関係をビルドする
同一パッケージのタスク	"dependsOn": ["codegen"]	先に同一パッケージ内で実行する
特定のパッケージ	"dependsOn": ["pkg#task"]	指定したパッケージのタスク
並列の lint/typecheck	トランジットノードパターン	順次実行せずにキャッシュを無効化する
開発サーバー	"persistent": true, "cache": false	長時間実行され、キャッシュされない
サイドカータスク	"with": ["api#dev"]	タスクと並行して実行する
ウォッチモード	turbo watch dev	ファイル変更時に再実行する
パッケージでフィルター	--filter=web	単一パッケージ
依存関係を含めてフィルター	--filter=web...	パッケージとその依存関係
変更されたパッケージ	--affected	変更されたパッケージとその依存先
キャッシュのデバッグ	--summarize または --dry	ハッシュの入力を確認する
パッケージ設定	"extends": ["//"] を含む turbo.json	パッケージごとの上書き
合成可能な設定	"extends": ["@repo/config"]	任意のワークスペースパッケージから拡張する
配列の拡張	配列内の "$TURBO_EXTENDS$"	継承した設定を置き換えずに追加する
ハッシュに含める環境変数	"env": ["API_URL"]	変更時にキャッシュを無効化する
境界	turbo boundaries	パッケージの分離とインポートルールを適用する
グラフのクエリ	turbo query	パッケージ／タスクグラフの GraphQL インターフェース
コード生成	turbo generate	新しいパッケージやコンポーネントのひな形を作成する
パッケージ一覧	turbo ls	モノレポ内のすべてのパッケージを一覧表示する
開発者ツール	turbo devtools	パッケージグラフとタスクグラフを視覚的に探索する
Docker 用にプルーニングしたワークスペース	turbo prune <pkg> --docker	コンテナビルド用の最小限のモノレポスライス

判断フロー

タスクを設定する

Configure a task?
+-- Define task dependencies       -> dependsOn in turbo.json
+-- Lint/check-types (parallel)    -> Transit Nodes pattern
+-- Specify build outputs          -> outputs key
+-- Handle environment variables   -> env key or globalEnv
+-- Dev/watch tasks                -> persistent: true, cache: false
+-- Sidecar tasks (run alongside)  -> with key
+-- Package-specific config        -> Package turbo.json with extends: ["//"]
+-- Composable config              -> extends from any workspace package
+-- Global settings                -> globalEnv, globalDependencies, cacheDir

キャッシュの問題

Cache problems?
+-- Outputs not restored           -> Missing outputs key
+-- Unexpected cache misses        -> Use --summarize or --dry to debug
+-- Skip cache entirely            -> --force or cache: false
+-- Remote cache not working       -> Check turbo login/link
+-- Environment causing misses     -> Var not in env key

パッケージをフィルターする

Filter packages?
+-- By package name                -> --filter=web
+-- By directory                   -> --filter=./apps/*
+-- Package + dependencies         -> --filter=web...
+-- Package + dependents           -> --filter=...web
+-- Changed + dependents           -> --affected

リポジトリを調べる

Explore repository?
+-- List all packages              -> turbo ls
+-- Query dependency graph         -> turbo query
+-- Visualize graphs               -> turbo devtools
+-- Check boundary violations      -> turbo boundaries
+-- Generate new package           -> turbo generate workspace
+-- Run custom generator           -> turbo generate run [name]

よくある間違い

間違い	正しいパターン
パッケージごとではなく、ルートの package.json スクリプトにビルドロジックを記述する	各パッケージでスクリプトを定義し、ルートで turbo run を使って処理を委譲します
workspace:* 依存関係を宣言せずに ^build を使用する	まず package.json に依存関係を追加します。^build が実行されるのは、宣言済みの依存関係に対してのみです
パッケージのスクリプト内で && を使って Turbo タスクを連結する	turbo.json の dependsOn を使ってタスクの順序を宣言します
環境変数を turbo.json の env キーに追加しない	キャッシュハッシュが正しく計算されるよう、ビルドに影響するすべての環境変数を env で宣言します
依存関係の順序を回避するために --parallel フラグを使用する	dependsOn を正しく設定するか、適切なキャッシュ無効化を行う並列タスクには中継ノードを使用します
古いスキーマ URL を使用する	$schema フィールドで https://turborepo.dev/schema.json を使用します
パッケージ設定で継承した配列を上書きする	置き換えるのではなく追加するには、配列内で $TURBO_EXTENDS$ を使用します
特定のパッケージに属するタスクをルートの turbo.json で定義する	extends: ["//"] を指定して、パッケージ独自の turbo.json 内でタスクを定義します
スクリプトや CI で turbo <task> の省略形を使用する	package.json のスクリプトや CI パイプラインでは turbo run <task> を使用します。省略形は対話的な使用に限ります

委譲

• モノレポ構造の調査：Explore エージェントを使って、パッケージ、ワークスペースのレイアウト、依存関係を調べます
• パイプラインの設定と最適化：Task エージェントを使って、turbo.json のタスク設定、キャッシュの構成、キャッシュミスのデバッグを行います
• モノレポアーキテクチャの計画：Plan エージェントを使って、パッケージの境界、共有ライブラリ、CI 最適化戦略を設計します

pnpm-workspace スキルが利用可能な場合は、ワークスペースのセットアップ、依存関係のリンク、カタログ、pnpm deploy を委譲します。 changesets スキルが利用可能な場合は、バージョン管理、変更履歴の生成、npm への公開を委譲します。

参考資料

• タスク設定と dependsOn のパターン
• キャッシュ、出力、キャッシュ問題のデバッグ
• フィルタリング、影響を受けるパッケージ、CI のパターン
• ワークスペース構造とパッケージ管理
• 環境変数とモード
• ウォッチモード、開発タスク、アンチパターン
• 境界、クエリ、コード生成