turborepo

Turborepo スキル

JavaScript／TypeScript のモノレポ向けビルドシステムです。Turborepo はタスクの出力をキャッシュし、依存関係グラフに基づいてタスクを並列実行します。

重要：ルートタスクではなくパッケージタスクを作成する

ルートタスクは作成しないでください。必ずパッケージタスクを作成してください。

タスク／スクリプト／パイプラインを作成するときは、必ず次の手順に従ってください。

1. 関連する各パッケージの package.json にスクリプトを追加します
2. ルートの turbo.json にタスクを登録します
3. ルートの package.json からは turbo run <task> を呼び出します

タスクのロジックをルートの package.json に記述しないでください。 そうすると、Turborepo の並列化が機能しなくなります。

// DO THIS: Scripts in each package
// apps/web/package.json
{ "scripts": { "build": "next build", "lint": "eslint .", "test": "vitest" } }

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

// packages/ui/package.json
{ "scripts": { "build": "tsc", "lint": "eslint .", "test": "vitest" } }

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

// Root package.json - ONLY delegates, no task logic
{
  "scripts": {
    "build": "turbo run build",
    "lint": "turbo run lint",
    "test": "turbo run test"
  }
}

// DO NOT DO THIS - defeats parallelization
// Root package.json
{
  "scripts": {
    "build": "cd apps/web && next build && cd ../api && tsc",
    "lint": "eslint apps/ packages/",
    "test": "vitest"
  }
}

ルートタスク（//#taskname）は、パッケージ内に作成できないタスク（まれなケース）に限って使用します。

副次的なルール：turbo run と turbo

コマンドをコードに記述するときは、必ず turbo run を使用してください。

// package.json - ALWAYS "turbo run"
{
  "scripts": {
    "build": "turbo run build"
  }
}

# CI workflows - ALWAYS "turbo run"
- run: turbo run build --affected

短縮形の turbo <tasks> は、人間またはエージェントがターミナルに直接入力する単発のコマンドに限って使用します。package.json、CI、スクリプトに turbo build を記述しないでください。

簡単な判断フロー

「タスクを設定したい」

Configure a task?
├─ Define task dependencies → references/configuration/tasks.md
├─ Lint/check-types (parallel + caching) → Use Transit Nodes pattern (see below)
├─ Specify build outputs → references/configuration/tasks.md#outputs
├─ Handle environment variables → references/environment/README.md
├─ Set up dev/watch tasks → references/configuration/tasks.md#persistent
├─ Package-specific config → references/configuration/README.md#package-configurations
└─ Global settings (cacheDir, daemon) → references/configuration/global-options.md

「キャッシュが機能していない」

Cache problems?
├─ Tasks run but outputs not restored → Missing `outputs` key
├─ Cache misses unexpectedly → references/caching/gotchas.md
├─ Need to debug hash inputs → Use --summarize or --dry
├─ Want to skip cache entirely → Use --force or cache: false
├─ Remote cache not working → references/caching/remote-cache.md
└─ Environment causing misses → references/environment/gotchas.md

「変更されたパッケージだけを実行したい」

Run only what changed?
├─ Changed packages + dependents (RECOMMENDED) → turbo run build --affected
├─ Custom base branch → --affected --affected-base=origin/develop
├─ Manual git comparison → --filter=...[origin/main]
└─ See all filter options → references/filtering/README.md

変更されたパッケージだけを実行するには、--affected を使用するのが基本です。 デフォルトブランチとの差分を自動的に比較し、依存先のパッケージも含めます。

「パッケージをフィルタリングしたい」

Filter packages?
├─ Only changed packages → --affected (see above)
├─ By package name → --filter=web
├─ By directory → --filter=./apps/*
├─ Package + dependencies → --filter=web...
├─ Package + dependents → --filter=...web
└─ Complex combinations → references/filtering/patterns.md

「環境変数が機能していない」

Environment issues?
├─ Vars not available at runtime → Strict mode filtering (default)
├─ Cache hits with wrong env → Var not in `env` key
├─ .env changes not causing rebuilds → .env not in `inputs`
├─ CI variables missing → references/environment/gotchas.md
└─ Framework vars (NEXT_PUBLIC_*) → Auto-included via inference

「CI を設定したい」

CI setup?
├─ GitHub Actions → references/ci/github-actions.md
├─ Vercel deployment → references/ci/vercel.md
├─ Remote cache in CI → references/caching/remote-cache.md
├─ Only build changed packages → --affected flag
├─ Skip unnecessary builds → turbo-ignore (references/cli/commands.md)
└─ Skip container setup when no changes → turbo-ignore

「開発中に変更を監視したい」

Watch mode?
├─ Re-run tasks on change → turbo watch (references/watch/README.md)
├─ Dev servers with dependencies → Use `with` key (references/configuration/tasks.md#with)
├─ Restart dev server on dep change → Use `interruptible: true`
└─ Persistent dev tasks → Use `persistent: true`

「パッケージを作成／構成したい」

Package creation/structure?
├─ Create an internal package → references/best-practices/packages.md
├─ Repository structure → references/best-practices/structure.md
├─ Dependency management → references/best-practices/dependencies.md
├─ Best practices overview → references/best-practices/README.md
├─ JIT vs Compiled packages → references/best-practices/packages.md#compilation-strategies
└─ Sharing code between apps → references/best-practices/README.md#package-types

「モノレポはどのように構成すればよいですか？」

Monorepo structure?
├─ Standard layout (apps/, packages/) → references/best-practices/README.md
├─ Package types (apps vs libraries) → references/best-practices/README.md#package-types
├─ Creating internal packages → references/best-practices/packages.md
├─ TypeScript configuration → references/best-practices/structure.md#typescript-configuration
├─ ESLint configuration → references/best-practices/structure.md#eslint-configuration
├─ Dependency management → references/best-practices/dependencies.md
└─ Enforce package boundaries → references/boundaries/README.md

「アーキテクチャ上の境界を強制したい」

Enforce boundaries?
├─ Check for violations → turbo boundaries
├─ Tag packages → references/boundaries/README.md#tags
├─ Restrict which packages can import others → references/boundaries/README.md#rule-types
└─ Prevent cross-package file imports → references/boundaries/README.md

重大なアンチパターン

コードで turbo の短縮形を使用する

package.json のスクリプトや CI パイプラインでは、turbo run の使用を推奨します。 短縮形の turbo <task> は、対話的なターミナル操作を目的としています。

// WRONG - using shorthand in package.json
{
  "scripts": {
    "build": "turbo build",
    "dev": "turbo dev"
  }
}

// CORRECT
{
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev"
  }
}

# WRONG - using shorthand in CI
- run: turbo build --affected

# CORRECT
- run: turbo run build --affected

Turbo を経由しないルートスクリプト

ルートの package.json スクリプトは、タスクを直接実行するのではなく、必ず turbo run を呼び出してください。

// WRONG - bypasses turbo entirely
{
  "scripts": {
    "build": "bun build",
    "dev": "bun dev"
  }
}

// CORRECT - delegates to turbo
{
  "scripts": {
    "build": "turbo run build",
    "dev": "turbo run dev"
  }
}

&& を使って Turbo のタスクを連結する

Turbo のタスクを && で連結しないでください。オーケストレーションは Turbo に任せてください。

// WRONG - turbo task not using turbo run
{
  "scripts": {
    "changeset:publish": "bun build && changeset publish"
  }
}

// CORRECT
{
  "scripts": {
    "changeset:publish": "turbo run build && changeset publish"
  }
}

依存パッケージを手動でビルドする prebuild スクリプト

他のパッケージを手動でビルドする prebuild のようなスクリプトは、Turborepo の依存関係グラフを経由しません。

// WRONG - manually building dependencies
{
  "scripts": {
    "prebuild": "cd ../../packages/types && bun run build && cd ../utils && bun run build",
    "build": "next build"
  }
}

ただし、修正方法はワークスペースの依存関係が宣言されているかどうかによって異なります。

1. 依存関係が宣言されている場合（例：package.json に "@repo/types": "workspace:*" と記載されている場合）、prebuild スクリプトを削除します。Turbo の dependsOn: ["^build"] が自動的に処理します。

2. 依存関係が宣言されていない場合、依存関係がないと ^build が実行されないため、prebuild が存在しています。次の手順で修正します。

   • package.json に依存関係を追加します："@repo/types": "workspace:*"
   • 次に、prebuild スクリプトを削除します

// CORRECT - declare dependency, let turbo handle build order
// package.json
{
  "dependencies": {
    "@repo/types": "workspace:*",
    "@repo/utils": "workspace:*"
  },
  "scripts": {
    "build": "next build"
  }
}

// turbo.json
{
  "tasks": {
    "build": {
      "dependsOn": ["^build"]
    }
  }
}

重要なポイント： ^build は、依存関係として指定されたパッケージでのみビルドを実行します。依存関係の宣言がなければ、ビルド順序は自動的に設定されません。

範囲が広すぎる globalDependencies

globalDependencies はすべてのパッケージのすべてのタスクに影響します。具体的に指定してください。

// WRONG - heavy hammer, affects all hashes
{
  "globalDependencies": ["**/.env.*local"]
}

// BETTER - move to task-level inputs
{
  "globalDependencies": [".env"],
  "tasks": {
    "build": {
      "inputs": ["$TURBO_DEFAULT$", ".env*"],
      "outputs": ["dist/**"]
    }
  }
}

繰り返しの多いタスク設定

まとめられるタスク間の重複設定がないか確認してください。Turborepo は設定を共有するパターンに対応しています。

// WRONG - repetitive env and inputs across tasks
{
  "tasks": {
    "build": {
      "env": ["API_URL", "DATABASE_URL"],
      "inputs": ["$TURBO_DEFAULT$", ".env*"]
    },
    "test": {
      "env": ["API_URL", "DATABASE_URL"],
      "inputs": ["$TURBO_DEFAULT$", ".env*"]
    },
    "dev": {
      "env": ["API_URL", "DATABASE_URL"],
      "inputs": ["$TURBO_DEFAULT$", ".env*"],
      "cache": false,
      "persistent": true
    }
  }
}

// BETTER - use globalEnv and globalDependencies for shared config
{
  "globalEnv": ["API_URL", "DATABASE_URL"],
  "globalDependencies": [".env*"],
  "tasks": {
    "build": {},
    "test": {},
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

グローバル設定とタスクレベルの設定の使い分け：

• globalEnv／globalDependencies — すべてのタスクに影響するため、本当に共有する設定に使用します
• タスクレベルの env／inputs — 特定のタスクだけが必要とする場合に使用します

アンチパターンではないもの：大きな env 配列

大きな env 配列（50 個以上の変数を含む場合でも）は問題ではありません。通常は、ビルドの環境依存関係をユーザーが丁寧に宣言していることを示します。これを問題として指摘しないでください。

--parallel フラグを使用する

--parallel フラグは、Turborepo の依存関係グラフを迂回します。タスクを並列実行する必要がある場合は、代わりに dependsOn を正しく設定してください。

# WRONG - bypasses dependency graph
turbo run lint --parallel

# CORRECT - configure tasks to allow parallel execution
# In turbo.json, set dependsOn appropriately (or use transit nodes)
turbo run lint

ルートの turbo.json におけるパッケージ固有のタスクオーバーライド

複数のパッケージで異なるタスク設定が必要な場合は、ルートの turbo.json に package#task のオーバーライドを追加して複雑にするのではなく、パッケージ設定（各パッケージの turbo.json）を使用してください。

// WRONG - root turbo.json with many package-specific overrides
{
  "tasks": {
    "test": { "dependsOn": ["build"] },
    "@repo/web#test": { "outputs": ["coverage/**"] },
    "@repo/api#test": { "outputs": ["coverage/**"] },
    "@repo/utils#test": { "outputs": [] },
    "@repo/cli#test": { "outputs": [] },
    "@repo/core#test": { "outputs": [] }
  }
}

// CORRECT - use Package Configurations
// Root turbo.json - base config only
{
  "tasks": {
    "test": { "dependsOn": ["build"] }
  }
}

// packages/web/turbo.json - package-specific override
{
  "extends": ["//"],
  "tasks": {
    "test": { "outputs": ["coverage/**"] }
  }
}

// packages/api/turbo.json
{
  "extends": ["//"],
  "tasks": {
    "test": { "outputs": ["coverage/**"] }
  }
}

パッケージ設定のメリット：

• 設定を、影響を受けるコードの近くに置けます
• ルートの turbo.json をクリーンに保ち、基本パターンに集中できます
• 各パッケージ固有の設定を把握しやすくなります
• $TURBO_EXTENDS$ を使って配列を継承・拡張できます

ルートで package#task を使用する場合：

• 1 つのパッケージに固有の依存関係が必要な場合（例："deploy": { "dependsOn": ["web#build"] }）
• 移行中の一時的なオーバーライド

詳細については、references/configuration/README.md#package-configurations を参照してください。

inputs で ../ を使用してパッケージの外に移動する

パッケージ外のファイルを参照するために、../ などの相対パスを使用しないでください。代わりに $TURBO_ROOT$ を使用してください。

// WRONG - traversing out of package
{
  "tasks": {
    "build": {
      "inputs": ["$TURBO_DEFAULT$", "../shared-config.json"]
    }
  }
}

// CORRECT - use $TURBO_ROOT$ for repo root
{
  "tasks": {
    "build": {
      "inputs": ["$TURBO_DEFAULT$", "$TURBO_ROOT$/shared-config.json"]
    }
  }
}

ファイルを生成するタスクに outputs がない

outputs がないことを指摘する前に、タスクが実際に何を生成するか確認してください：

1. パッケージのスクリプトを読む（例："build": "tsc"、"test": "vitest"）
2. ファイルをディスクに書き込むか、stdout に出力するだけかを確認する
3. キャッシュすべきファイルをタスクが生成する場合にのみ指摘する

// WRONG: build produces files but they're not cached
{
  "tasks": {
    "build": {
      "dependsOn": ["^build"]
    }
  }
}

// CORRECT: build outputs are cached
{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    }
  }
}

フレームワークごとの一般的な出力：

• Next.js：[".next/**", "!.next/cache/**"]
• Vite/Rollup：["dist/**"]
• tsc：["dist/**"] またはカスタムの outDir

TypeScript の --noEmit でもキャッシュファイルが生成されることがあります：

tsconfig.json で incremental: true が設定されている場合、tsc --noEmit は JS を出力しなくても .tsbuildinfo ファイルを書き込みます。出力がないと判断する前に、tsconfig を確認してください：

// If tsconfig has incremental: true, tsc --noEmit produces cache files
{
  "tasks": {
    "typecheck": {
      "outputs": ["node_modules/.cache/tsbuildinfo.json"] // or wherever tsBuildInfoFile points
    }
  }
}

TypeScript タスクの正しい出力を判断するには：

1. tsconfig で incremental または composite が有効か確認する
2. カスタムのキャッシュ場所を指定する tsBuildInfoFile を確認する（デフォルト：outDir の隣、またはプロジェクトルート）
3. インクリメンタルモードが無効な場合、tsc --noEmit はファイルを生成しません

^build と build の混同

{
  "tasks": {
    // ^build = run build in DEPENDENCIES first (other packages this one imports)
    "build": {
      "dependsOn": ["^build"]
    },
    // build (no ^) = run build in SAME PACKAGE first
    "test": {
      "dependsOn": ["build"]
    },
    // pkg#task = specific package's task
    "deploy": {
      "dependsOn": ["web#build"]
    }
  }
}

環境変数がハッシュ化されない

// WRONG: API_URL changes won't cause rebuilds
{
  "tasks": {
    "build": {
      "outputs": ["dist/**"]
    }
  }
}

// CORRECT: API_URL changes invalidate cache
{
  "tasks": {
    "build": {
      "outputs": ["dist/**"],
      "env": ["API_URL", "API_KEY"]
    }
  }
}

.env ファイルが inputs に含まれていない

Turbo は .env ファイルを読み込みません。読み込むのはフレームワークです。ただし、Turbo は変更を認識する必要があります：

// WRONG: .env changes don't invalidate cache
{
  "tasks": {
    "build": {
      "env": ["API_URL"]
    }
  }
}

// CORRECT: .env file changes invalidate cache
{
  "tasks": {
    "build": {
      "env": ["API_URL"],
      "inputs": ["$TURBO_DEFAULT$", ".env", ".env.*"]
    }
  }
}

モノレポのルートにある .env ファイル

リポジトリルートに .env ファイルを置くのはアンチパターンです。小規模なモノレポやスターターテンプレートでも同様です。パッケージ間に暗黙の結合が生じ、どのパッケージがどの変数に依存するのかが不明確になります。

// WRONG - root .env affects all packages implicitly
my-monorepo/
├── .env              # Which packages use this?
├── apps/
│   ├── web/
│   └── api/
└── packages/

// CORRECT - .env files in packages that need them
my-monorepo/
├── apps/
│   ├── web/
│   │   └── .env      # Clear: web needs DATABASE_URL
│   └── api/
│       └── .env      # Clear: api needs API_KEY
└── packages/

ルートの .env に関する問題：

• どのパッケージがどの変数を使用するのか不明確です
• すべてのパッケージがすべての変数を取得します（必要のないものも含みます）
• キャッシュ無効化の粒度が粗くなります（ルートの .env が変更されると、すべてが無効になります）
• セキュリティ上のリスクがあります。パッケージが、他のパッケージ向けの機密変数に誤ってアクセスする可能性があります
• 悪い習慣は小さなところから始まります。スターターテンプレートでは正しいパターンを示すべきです

変数を共有する必要がある場合は、globalEnv を使って共有する内容を明示し、その理由をドキュメントに記載してください。

Strict モードでの CI 変数のフィルタリング

デフォルトでは、Turborepo は環境変数を env／globalEnv に指定されたものだけに絞り込みます。CI 変数が欠落する場合があります：

// If CI scripts need GITHUB_TOKEN but it's not in env:
{
  "globalPassThroughEnv": ["GITHUB_TOKEN", "CI"],
  "tasks": { ... }
}

または --env-mode=loose を使用してください（本番環境では推奨されません）。

アプリ内の共有コード（パッケージにすべきもの）

// WRONG: Shared code inside an app
apps/
  web/
    shared/          # This breaks monorepo principles!
      utils.ts

// CORRECT: Extract to a package
packages/
  utils/
    src/utils.ts

パッケージ境界を越えたファイルへのアクセス

// WRONG: Reaching into another package's internals
import { Button } from "../../packages/ui/src/button";

// CORRECT: Install and import properly
import { Button } from "@repo/ui/button";

ルートの依存関係が多すぎる

// WRONG: App dependencies in root
{
  "dependencies": {
    "react": "^18",
    "next": "^14"
  }
}

// CORRECT: Only repo tools in root
{
  "devDependencies": {
    "turbo": "latest"
  }
}

一般的なタスク設定

標準的なビルドパイプライン

{
  "$schema": "https://turborepo.dev/schema.v2.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

キャッシュ無効化を伴いながら並列実行する必要があるタスクがある場合は、transit タスクを追加してください（以下を参照）。

^dev パターンを使った Dev タスク（turbo watch 用）

ルートの turbo.json にある dependsOn: ["^dev"] と persistent: false を設定した dev タスクは、一見変わっているように見えるかもしれませんが、turbo watch のワークフローでは正しい設定です。

// Root turbo.json
{
  "tasks": {
    "dev": {
      "dependsOn": ["^dev"],
      "cache": false,
      "persistent": false  // Packages have one-shot dev scripts
    }
  }
}

// Package turbo.json (apps/web/turbo.json)
{
  "extends": ["//"],
  "tasks": {
    "dev": {
      "persistent": true  // Apps run long-running dev servers
    }
  }
}

この設定が機能する理由：

• パッケージ（例：@acme/db、@acme/validators）では、"dev": "tsc" を設定します。これはすぐに完了する、1 回限りの型生成処理です。
• アプリでは、実際の開発サーバー（Next.js など）を起動するために persistent: true で上書きします。
• turbo watch は、ソースファイルの変更時にパッケージの 1 回限りの dev スクリプトを再実行し、型を最新の状態に保ちます。

想定される使い方： turbo run dev ではなく、turbo watch dev を実行します。ウォッチモードでは、永続タスクを実行したまま、ファイルの変更時に 1 回限りのタスクを再実行します。

代替パターン： 意図がより明確になるよう、依存関係の 1 回限りのビルドには prepare や generate などの別のタスク名を使います。

{
  "tasks": {
    "prepare": {
      "dependsOn": ["^prepare"],
      "outputs": ["dist/**"]
    },
    "dev": {
      "dependsOn": ["prepare"],
      "cache": false,
      "persistent": true
    }
  }
}

キャッシュ無効化を伴う並列タスクのための中継ノード

タスクの中には、並列実行できるもの（依存関係のビルド出力を必要としないもの）がありますが、依存関係のソースコードが変更されたときにはキャッシュを無効化する必要があります。

dependsOn: ["^taskname"] の問題：

• 順次実行を強制します（低速です）。

dependsOn: []（依存関係なし）の問題：

• 並列実行が可能です（高速です）。
• ただし、キャッシュが正しくありません。依存関係のソースを変更しても、キャッシュは無効化されません。

中継ノードなら、両方の問題を解決できます。

{
  "tasks": {
    "transit": { "dependsOn": ["^transit"] },
    "my-task": { "dependsOn": ["transit"] }
  }
}

transit タスクは、実際のスクリプトには一致しない依存関係を作成するため、正しいキャッシュ無効化を保ちながらタスクを並列実行できます。

このパターンが必要なタスクを特定する方法： 依存関係のソースファイルを読み込むものの、依存関係のビルド出力を必要としないタスクを探します。

環境変数を使用する場合

{
  "globalEnv": ["NODE_ENV"],
  "globalDependencies": [".env"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"],
      "env": ["API_URL", "DATABASE_URL"]
    }
  }
}

リファレンス一覧

設定

ファイル	目的
configuration/README.md	turbo.json の概要、パッケージ設定
configuration/tasks.md	dependsOn、outputs、inputs、env、cache、persistent
configuration/global-options.md	globalEnv、globalDependencies、cacheDir、daemon、envMode
configuration/gotchas.md	よくある設定ミス

キャッシュ

ファイル	目的
caching/README.md	キャッシュの仕組み、ハッシュ入力
caching/remote-cache.md	Vercel Remote Cache、セルフホスト可能、ログイン／リンク
caching/gotchas.md	キャッシュミスのデバッグ、--summarize、--dry

環境変数

ファイル	目的
environment/README.md	env、globalEnv、passThroughEnv
environment/modes.md	Strict モードと Loose モード、フレームワーク推論
environment/gotchas.md	.env ファイル、CI の問題

フィルタリング

ファイル	目的
filtering/README.md	--filter 構文の概要
filtering/patterns.md	一般的なフィルターパターン

CI/CD

ファイル	目的
ci/README.md	CI の基本原則
ci/github-actions.md	GitHub Actions の完全なセットアップ
ci/vercel.md	Vercel のデプロイ、turbo-ignore
ci/patterns.md	--affected、キャッシュ戦略

CLI

ファイル	目的
cli/README.md	turbo run の基本
cli/commands.md	turbo run のフラグ、turbo-ignore、その他のコマンド

ベストプラクティス

ファイル	目的
best-practices/README.md	モノレポのベストプラクティスの概要
best-practices/structure.md	リポジトリ構造、ワークスペース設定、TypeScript/ESLint のセットアップ
best-practices/packages.md	内部パッケージの作成、JIT とコンパイル、エクスポート
best-practices/dependencies.md	依存関係の管理、インストール、バージョンの同期

ウォッチモード

ファイル	目的
watch/README.md	turbo watch、中断可能なタスク、開発ワークフロー

境界（試験的）

ファイル	目的
boundaries/README.md	パッケージの分離を徹底し、タグベースの依存関係ルールを設定

ソースドキュメント

このスキルは、Turborepo の公式ドキュメントを基にしています。

• ソース：Turborepo リポジトリ内の docs/site/content/docs/
• 公開版：https://turborepo.dev/docs