turborepo（Turborepo Monorepo 构建）

Turborepo Skill

Build system guidance for JavaScript and TypeScript monorepos using Turborepo.

Core Rules

1. Create package tasks, not root tasks.
2. Register task behavior in turbo.json.
3. Let root package.json delegate with turbo run <task>.
4. Use turbo <task> only for interactive one-off terminal commands, not in committed code.
5. Declare workspace dependencies in package.json so dependsOn: ["^build"] can resolve actual package relationships.

Baseline Pattern

// 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"
  }
}

Quick Routing

Read only the reference files needed for the task:

Decision Trees

Configure a Task

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

Debug Caching

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

Run Only Changed Work

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

Set Up 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

Structure the Monorepo

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

High-Signal Anti-Patterns

• Root scripts that bypass Turborepo entirely. Root scripts should delegate with turbo run, not embed app-specific task logic.
• Committed turbo build or turbo lint commands in package.json, CI, or scripts. Use turbo run... in committed code.
• Manual prebuild chains that compile sibling packages instead of declaring workspace dependencies and using ^build.
• Missing outputs on tasks that write files. Read the actual script before deciding whether a task is cacheable.
• Environment variables omitted from env or .env files omitted from inputs, causing stale cache hits.
• Root-level .env files in a monorepo, which create hidden coupling between packages.
• Relative imports or file traversal across package boundaries instead of importing through package APIs.
• Package-specific overrides cluttering root turbo.json instead of using per-package turbo.json files.

See the detailed examples in:

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

Common Configurations

Standard Build + Dev

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

Transit Node for Parallel Tasks With Correct Cache Invalidation

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

Use this when a task can run in parallel but still needs dependency source changes to invalidate its cache.

Watch Mode Pattern

Use turbo watch for file-change loops, not turbo run... --watch patterns improvised in scripts. Read references/watch/RULE.md before configuring persistent, interruptible, or with.

Validation Checklist

• Every committed command in code or CI uses turbo run....
• Tasks live in package scripts; root scripts only delegate.
• dependsOn matches the actual dependency relationship: ^task for upstream packages, task for same-package prerequisites.
• Cacheable file-producing tasks declare outputs.
• Relevant environment variables are in env or globalEnv.
• Relevant .env files are represented in inputs.
• Workspace packages import each other through package names, not relative source paths.
• CI uses --affected or filters when appropriate instead of rebuilding everything by default.

Source Documentation

Based on official Turborepo docs: apps/docs/content/docs/ — https://turborepo.dev/docs