turborepo

Turborepo Skill

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

This SKILL.md is an index. When you need the detail for a topic, Read the matching references/<topic>.md file — don't work from memory.

When to use

Use when the user: configures tasks/workflows/pipelines, creates packages, sets up a monorepo, shares code between apps, runs changed/affected packages, debugs the cache, sets up CI, enforces package boundaries, or is working in a repo with apps//packages/ directories or a turbo.json.

Two rules that always apply

1. Package tasks, not Root Tasks. Put task logic (scripts) in each package's package.json, register the task in root turbo.json, and let root package.json only delegate via turbo run <task>. Root Tasks (//#taskname) are a rare exception. See references/tasks-pipeline.md.
2. turbo run, not turbo, in code. Always write turbo run <task> in package.json scripts and CI. The bare turbo <task> shorthand is only for one-off interactive terminal use. See references/tasks-pipeline.md.

Decision tree → which reference to read

What are you doing?
├─ Configuring a task / pipeline (dependsOn, outputs, transit nodes, dev/watch) → tasks-pipeline.md
├─ Cache not working / wrong cache hits / debugging hashes              → caching.md
├─ Sharing cache across machines / CI                                   → remote-cache.md
├─ Running only changed packages / --filter / --affected                → filtering.md
├─ Setting up CI (GitHub Actions, Vercel, turbo-ignore)                 → ci.md
├─ Env vars not available / wrong cache from env / .env files           → env-vars.md
├─ Creating a package / structuring the monorepo / dependencies         → packages.md
└─ Enforcing import/architectural boundaries                            → boundaries.md

Topic index

Topic	Read this	Covers
Tasks & pipeline	references/tasks-pipeline.md	Package-vs-Root tasks, turbo run rule, dependsOn/^build, outputs, transit nodes, dev/watch patterns, task anti-patterns
Caching	references/caching.md	Hash inputs, missing outputs, env/.env hashing, globalDependencies, debugging misses
Remote cache	references/remote-cache.md	Vercel Remote Cache, self-hosted, turbo login/link
Filtering & affected	references/filtering.md	--affected, --filter by name/dir/..., change-set runs
CI / CD	references/ci.md	GitHub Actions, Vercel, turbo-ignore, --affected in CI, passthrough env
Env vars	references/env-vars.md	env/globalEnv/passThroughEnv, strict vs loose, root .env anti-pattern
Packages & structure	references/packages.md	Internal packages, apps//packages/ layout, deps, JIT vs compiled
Boundaries	references/boundaries.md	turbo boundaries, tags, tag-based import rules

Deeper reference subtrees

The topic files above link into the detailed references/ subtrees when you need full mechanics:

• Configuration — configuration/RULE.md (turbo.json overview, Package Configurations), configuration/tasks.md (dependsOn, outputs, inputs, env, cache, persistent), configuration/global-options.md (globalEnv, globalDependencies, global key, futureFlags, cacheDir, envMode), configuration/gotchas.md.
• Caching — caching/RULE.md, caching/remote-cache.md, caching/gotchas.md (--summarize, --dry).
• Environment — environment/RULE.md, environment/modes.md, environment/gotchas.md.
• Filtering — filtering/RULE.md, filtering/patterns.md.
• CI/CD — ci/RULE.md, ci/github-actions.md, ci/vercel.md, ci/patterns.md.
• CLI — cli/RULE.md, cli/commands.md (turbo run flags, turbo-ignore, other commands).
• Best practices — best-practices/RULE.md, best-practices/structure.md, best-practices/packages.md, best-practices/dependencies.md.
• Watch mode — watch/RULE.md (turbo watch, interruptible tasks, dev workflows).
• Boundaries — boundaries/RULE.md.

Source Documentation

This skill is based on the official Turborepo documentation:

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