Inspect the local Turborepo surface before changing code:
- Package versions for turbo / create-turbo (2.x line; snapshot 2.11.6). Many features below need 2.10+ (deferred hashing, cache eviction) or the 2.11 release (devEngines.packageManager, nub/aube, prune --production — first shipped in 2.10.1–2.10.3 patches; native Rust/Python/Go need 2.11; task tags need 2.11.6).
- Root turbo.json / turbo.jsonc, package-level turbo.json, workspace globs, lockfile, devEngines.packageManager / packageManager.
- Root and package package.json scripts that turbo invokes.
- CI remote-cache env (TURBO_TOKEN, TURBO_TEAM), prune/Docker usage, --affected / filters, futureFlags in root turbo.json.
For setup, day-to-day runs, progressive adoption, baselines, and troubleshooting, follow the full guide first: usage-guide.md.
Refresh current official docs when versions differ from the snapshot or the work touches caching, env hashing, prune, or future flags. Start from source-map.md.
Route deeper detail:
- Task graph, dependsOn/with, inputs/outputs, package configs: turbo-json-tasks.md.
- turbo run, filters, --affected, watch, generators: cli-filtering-watch.md.
- Local/remote cache, eviction, env modes, framework inference: caching-env-remote.md.
- CI vendors, prune, Docker: ci-docker-prune.md.
- Internal packages, framework/tool graphs, boundaries, package managers, Rust/Python/Go toolchains, migrations: packages-integrations.md.
Preserve the repository's package manager and existing script names unless the user asks to migrate them.
Verify with the narrowest useful bunx turbo run … (--dry, --filter, or --affected).

Core Judgment

Turborepo orchestrates existing package.json scripts. It is not a package manager and not a replacement for workspaces.
Prefer turbo run <tasks> in CI (not bare turbo build) so future CLI subcommands do not collide with task names.
Declare outputs for every cacheable build task. Missing outputs → cache hits restore nothing useful.
Use "dependsOn": ["^build"] for dependency builds; "dependsOn": ["build"] for same-package ordering. Do not confuse them.
Default envMode is strict. List hash-affecting vars in env / globalEnv; use passThroughEnv only when values must not bust the cache.
Never recurse: package scripts must not call turbo run for the same task turbo is already running.
Mark dev / watch / servers "cache": false and "persistent": true. Use "with" to co-run related persistent tasks.
Prefer --cache=local:…,remote:… over deprecated --no-cache / --remote-only.
Install dependencies where used (not root-hoisted) for better cache/prune fidelity.
Prefer transit nodes (topo / transit) for parallel typecheck over TypeScript Project References with Turbo.
Lint/format tools (for example Oxlint and Oxfmt) often fit as root tasks //#lint / //#format.
For files written by an upstream task (codegen) or dependency outputs (.d.ts), use deferred inputs objects ({ "mode": "jit" } / { "mode": "dependencyOutputs" }) instead of cache: false.
Declare the package manager with devEngines.packageManager (2.10.1+, announced with 2.11). Top-level packageManager still works but is slated for removal in a future major.
Changing any futureFlags entry busts the global hash (every task misses once). Set them only in the root turbo.json.
Since 2.11.5, when turbo detects a coding agent it keeps a managed Turborepo block in the root AGENTS.md (default agentGuidance: true). Expect that diff; set root "agentGuidance": false to opt out.
Rust (Cargo), Python (uv), and Go (go.work) workspaces are experimental future flags — do not enable them in production CI unless the user asks.

Verification

Prefer repository-owned commands. For meaningful Turborepo work, cover the relevant subset:

bunx turbo run <task> --dry=json or --graph to validate the DAG before expensive runs.
Focused bunx turbo run <task> --filter=<pkg> then widen to --affected when CI-shaped.
Cache correctness: change an input/env → expect miss; unchanged → expect hit (--summarize if hashing is unclear).
Remote cache smoke when changing TURBO_* or remoteCache config.
Prune/Docker: turbo prune <app> --docker then install+build from out/ when changing deploy graphs.
Watch/dev: confirm interruptible / with / persistent behavior for long-running tasks.

Report which checks ran, which did not, and any turbo-version or remote-cache assumptions that remain.

turborepo

Turborepo

Workflow