Turborepo

Turborepo Skill

Build system for JavaScript/TypeScript monorepos. Turborepo caches task outputs and runs tasks in parallel based on dependency graph.

IMPORTANT: Package Tasks, Not Root Tasks

DO NOT create Root Tasks. ALWAYS create package tasks.

When creating tasks/scripts/pipelines, you MUST:

1. Add the script to each relevant package's package.json
2. Register the task in root turbo.json
3. Root package.json only delegates via turbo run <task>

DO NOT put task logic in root package.json. This defeats Turborepo's parallelization.

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

Root Tasks (//#taskname) are ONLY for tasks that truly cannot exist in packages (rare).

Secondary Rule: turbo run vs turbo

Always use turbo run when the command is written into code:

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

The shorthand turbo <tasks> is ONLY for one-off terminal commands typed directly by humans or agents. Never write turbo build into package.json, CI, or scripts.

Quick Decision Trees

Critical Anti-Patterns

See references/anti-patterns.md for: using turbo shorthand, root scripts bypassing turbo, prebuild scripts, missing outputs, env vars not hashed, root .env files, and more.

Common Task Configurations

Ready-to-use patterns at references/task-configurations.md: standard build pipeline, dev task with ^dev pattern, transit nodes, lint/type-check setup, test pipeline with coverage.

Reference Index

Source Documentation

• Source: docs/site/content/docs/ in the Turborepo repository
• Live: https://turborepo.dev/docs