vercel/turborepo
github.com/vercel/turborepo ↗ · 4000 files · 12.4 MB · scan capped
Turborepo Turborepo is the build system for coding agents.
Overview
Turborepo is a Rust-based build orchestrator for developers and coding agents working across repository packages. It discovers packages, constructs task graphs, hashes inputs, executes native toolchain commands, and restores reusable outputs from local or authenticated remote caches. This commit also includes experimental Rust, Python, and Go workspace support, repository inspection tools, JavaScript scaffolding and migration packages, a documentation site, and an internal agent workspace application.
System map
The principal product is a native CLI organized into focused Rust crates. Startup, repository discovery, task scheduling, process execution, caching, and output rendering have separate owners. JavaScript packages and Next.js applications surround the CLI with distribution, onboarding, documentation, and internal operator tooling.
- The turbo binary handles internal LSP commands before normal startup, installs the panic handler, and delegates ordinary execution to turborepo_cli::main.
- The binary injects TurboQueryServer because it depends on both the CLI and GraphQL implementation; query execution is exposed through the QueryServer interface.
- CLI argument parsing precedes Rayon and Tokio startup; run_main owns command dispatch and runtime shutdown uses shutdown_background.
- RunBuilder::build assembles discovery results, AsyncCache, an execution context, run services, and a repository context into Run.
- Local cache storage uses hash-named .tar.zst archives plus restore-manifest and metadata JSON sidecars.
- The npm turbo package distributes a launcher, bundled docs, and schema.json, with version-matched optional binaries for macOS, Linux, and Windows on two architectures.
- The root provides build:turbo and turbo scripts, pins Node 24 and pnpm 12, and registers Rust crates and the repository addon in the Cargo workspace.
- apps/docs is a Next.js documentation application; apps/factory is a separate operator surface whose documented workspace storage uses private Blob objects and Vercel Sandbox sessions.
Feature catalog
The inspected command dispatcher exposes execution, watching, pruning, inspection, authentication, generation, and configuration features. Execution supports terminal, TUI, and machine-readable output, alongside graph and dry-run modes. Additional package and application surfaces support project creation, configuration migration, and durable agent workspaces; this catalog is bounded by the inspected files.
- Task runs support structured JSON output, a TUI or streamed terminal output, graph output, and JSON dry runs; machine-readable modes suppress competing stdout.
- turbo watch constructs WatchClient with experimental_write_cache, requires tasks, treats SignalInterrupt as normal termination, and explicitly shuts down the client.
- turbo prune accepts scope, Docker layout, production mode, output directory, and gitignore behavior; its CLI adapter passes repository options and future flags to turborepo-prune.
- Inspection commands include boundaries, devtools, info, config, ls, and GraphQL query; query and ls reject execution when no QueryServer is available.
- Login supports standard, manual, and SSO branches; standard Vercel login uses OAuth device authorization while self-hosted login uses a localhost redirect.
- The dispatcher also exposes daemon client/server operation, documentation lookup, generation with custom arguments, and telemetry configuration; scan only emits a deprecation warning and returns 1.
- Experimental native workspace support covers Cargo crates, uv Python packages, and go.work modules, each gated by its ecosystem-specific future flag.
- Companion features include create-turbo template selection, dynamically loaded codemod transformers, turbo-trace forward/reverse dependency tracing, and Factory's durable workspace UI.
Data flow
CLI arguments and inferred repository state establish the execution boundary. Discovery and configuration become immutable repository and execution contexts, while file, dependency, and environment inputs feed task hashes. Task results flow through completion callbacks, output sinks, and caches; authentication has a separate user-level persistence path.
- run_main combines inferred RepoState and --cwd to select the repository root, canonicalizes it on Windows, and applies repository/package inference to command flags.
- RepositoryContributor separates cheap scope inventory from authoritative package discovery; inventory must not supply tasks, relationships, resolution facts, or prune domains.
- RunBuilder passes discovered package graphs, SCM, lazy plans, and AsyncCache into build_execution_context, then creates service and repository owners before returning Run.
- TaskHashable combines global and dependency hashes, package directory, file and external-dependency hashes, outputs, arguments, environment settings, and command overrides into the cache key.
- ToolchainCommandProvider resolves native task specifications or authoritative argv overrides, assigns cwd and serial groups, and clears inherited environment before applying the selected map.
- Engine::execute sends task IDs through a visitor channel and waits on completion results; StopExecution controls cancellation or dependent-subgraph traversal.
- TaskCache restores through AsyncCache using the repository root and task hash; saves expand output globs, isolate managed logs, reject paths outside the repository, and put relative paths with duration.
- Login converts TokenSet expiry into an absolute timestamp and persists token/refresh metadata to user configuration; vca_ tokens go to Turbo auth storage while stale alternate storage is cleared.
Behavior traces
Three concrete flows were followed: CLI startup, task execution with cache persistence, and standard login with credential persistence. The traces retain branches that change execution, including local-binary selection, graph-only runs, cache hits, cache failures, and existing-token reuse. These are source-derived execution sequences, not runtime observations.
- Startup: binary main → turborepo_cli::main → raise_open_file_limit → shim::run; internal LSP requests return before this ordinary path.
- Startup continues: normalize_config_dir_env_vars → ShimArgs::parse → TurboSubscriber construction → ShimRuntime::new → run_with_args; TurboCliRunner then delegates to cli::run.
- CLI startup: Args::new → init_rayon_pool → Tokio runtime → run_main → deferred telemetry initialization → get_command → inference flags and repository root → agent guidance maintenance.
- Run setup: commands::run creates signals and log sinks → RunBuilder::new → execute_run → run_with_ui → RunBuilder::build → start_ui → Run::run.
- Run execution: Run::run starts proxy/shutdown services; graph mode writes the graph and returns 0, otherwise execute_visitor constructs Visitor, enables dry-run when requested, visits the engine, and derives the exit code.
- Task branch: execute_inner → restore_outputs; a hit updates the hash tracker and skips spawning, while a miss or logged fetch error proceeds through serial-group locking to ProcessManager::spawn.
- Persistence branch: execute flushes output and sends the completion callback before save_outputs; only a successful Run outcome is eligible, and FSCache writes archive entries, atomically finishes the archive, then writes sidecars.
- Standard login: login → login_no_sso → auth_login; reusable credentials return without writing, otherwise Vercel device login performs discover → authorization request → poll_for_token → get_user, then write_token persists the returned credentials.
Testing signals
Tests and CI were inspected, not executed; no passing result is asserted. The inspected coverage includes Rust integration behavior, executor policies, archive safety regressions, GraphQL host checks, and Jest package tests. CI spans multiple operating systems and Node versions, but exclusions, mocked boundaries, and release-PR skips limit what any individual job establishes.
- Rust integration tests under crates/turborepo/tests use #[test], temporary repositories, shared setup helpers, and subprocess output assertions; run_caching checks env-sensitive misses/hits and JSON cache metadata.
- Executor unit tests cover all three continuation policies and ensure cache hits, output-flush failures, task failures, shutdowns, restarts, and internal errors do not trigger output saving.
- Archive regression tests include an existing symlink pointing outside the restore anchor and assert replacement with a directory plus no external write.
- Query-server tests check GraphiQL response content and allowed/rejected host strings; the displayed tests call helper functions rather than exercising live HTTP middleware.
- create-turbo and turbo-utils use Jest; inspected tests include starter agent guidance and mocked child-process/fetch boundaries, so these examples do not establish live download or toolchain success.
- Rust CI uses macOS, Ubuntu, and Windows with two hash partitions; turbo.json invokes nextest while excluding LSP, schema generation, and N-API from that workspace test task.
- JavaScript CI covers Ubuntu/macOS and Node 22/24/26, runs affected package checks in strict env mode, excludes @turbo/repository from this job, and skips the job for validated release PRs.
- Lint CI separately configures cargo fmt, cargo lint, and license checking; nextest limits experimental OTel integration tests to one minute with no retries.
Risk map
The following are security-sensitive boundaries and source-observed coupling points, not confirmed vulnerabilities. Native command execution, archive restoration, user-level credentials, remote cache authorization, and internal operator deployment protection deserve focused review. The bounded inspection does not establish whole-repository coverage or the absence of other risks.
- Task command configuration can replace native commands or opt out entirely; executable, arguments, cwd, and environment are applied before spawning, making repository task definitions an execution trust boundary.
- Archive restore writes into the anchor and supports directories, regular files, and symlinks; Unix regular-file permissions are masked to 0777 and unsupported entry types fail.
- Output collection follows symlinked output roots, filters peer managed logs, and rejects paths outside the repository; restoration currently fetches the artifact without using output globs to restrict extraction.
- Login persists access and refresh tokens outside the repository through create_with_contents_secret; credential routing distinguishes vca_ tokens from legacy tokens and clears alternate storage.
- Artifact signing uses TURBO_REMOTE_CACHE_SIGNATURE_KEY and binds hash, team ID, and body length; short-key enforcement is conditional, with warning-only compatibility unless longerSignatureKey is enabled.
- Remote-cache token recovery is serialized and retries with changed credentials; failed recovery disables remote caching for the run, while task cache-fetch errors are logged before execution continues.
- The GraphQL service binds 127.0.0.1:8000 and rejects Host values outside localhost/127.0.0.1, explicitly guarding its local HTTP exposure.
- Factory documents Vercel Deployment Protection as its outer operator authentication layer and same-origin/action-header checks for mutations; deployment protection configuration is therefore a material access-control dependency.
Extension points
The core extends through explicit traits, typed configuration, and centralized command dispatch. Repository contributors supply ecosystem knowledge, command providers supply executable specifications, and query interfaces keep GraphQL implementation outside the CLI dependency boundary. Companion packages add filesystem-discovered transformations, while output changes follow a shared logging architecture.
- New ecosystem integrations implement RepositoryContributor::id, discover_packages, and discover_package_scopes; conservative static dependencies are an optional separate hook.
- CommandFactory::add_provider registers ordered CommandProvider implementations; the first Some command wins and any provider error immediately propagates.
- EngineProvider exposes tasks, definitions, and dependencies, while EngineExecutor accepts concurrency and a message sender, permitting execution support to depend on interfaces.
- QueryServer injection enables alternate query implementations or CLI builds without queries; the binary's adapter delegates execute_query and run_query_server to turborepo-query.
- CLI dispatch is centralized in the Command match; additions must connect parsed commands to their command adapters, telemetry events, and CommandBase requirements.
- The public TypeScript schema maps task names to Pipeline definitions and exposes workspace extends, tags, and boundaries configuration.
- Codemods plug in as default-exported Transformer modules discovered from the transforms directory; loadTransformers ignores loading errors and filters empty results.
- New logging areas add Subsystem variants; user-facing events and task bytes pass through GroupingLayer and Logger to terminal, TUI, and file/collector sinks.
Contributor handoff
This handoff is grounded in the pinned commit and a clean tracked working-tree comparison, with bounded inspection rather than exhaustive coverage. Tests and CI were inspected, not executed; commands below are documented future checks, not results. Begin at the owning crate and preserve discovery authority, hash inputs, output modes, credential routing, and completion semantics.
- Read AGENTS.md and CONTRIBUTING.md before changes: repository rules prohibit bypassing commit/push hooks and require Conventional Commit PR titles with uppercase descriptions and no scopes.
- For CLI changes, keep main.rs thin and follow lib.rs → shim.rs → cli/mod.rs; the binary explicitly directs additional logic into turborepo_cli::main.
- Use the repository's Node 24/pnpm 12 versions and existing build:turbo script; Rust code inherits edition 2024 and workspace Clippy restrictions on expect and unwrap.
- Documented focused verification is cargo test -p <module> or cargo test -p turbo --test <target>, with cargo lint for Clippy; these checks were inspected, not executed in this audit.
- When execution is authorized, manual development-binary testing requires --skip-infer; CONTRIBUTING also distinguishes deprecated run-daemon behavior from watch's daemon use.
- Do not collapse scope inventory into full discovery or change hash inputs casually: contributor contracts forbid invented task knowledge and TaskHashable includes command, environment, dependency, and output semantics.
- Preserve callback-before-cache-save ordering and JSON stdout ownership; these behaviors are explicit in the executor and run adapter and affect dependents and machine consumers.
- A turbo invocation under a detected agent can update AGENTS.md when bundled docs and configuration permit it; maintenance uses a PID lock and refuses replacement after concurrent edits.
Languages
| Language | Files | Share of source |
|---|---|---|
| JSON | 2051 | docs/config |
| TypeScript | 921 | 46% |
| Rust | 567 | 28% |
| JavaScript | 372 | 19% |
| Markdown | 371 | docs/config |
| YAML | 238 | docs/config |
| TOML | 110 | 6% |
| CSS | 76 | docs/config |
Start reading here
Probable source entrypoint: Cargo.toml — inferred from the directory tree and manifest, not the upstream docs.
Source roots
crates/ (658 files) packages/ (657 files)
Repository structure
| Top-level path | Files |
|---|---|
examples/ | 658 |
crates/ | 658 |
lockfile-tests/ | 657 |
turborepo-tests/ | 657 |
packages/ | 657 |
apps/ | 628 |
.github/ | 32 |
scripts/ | 12 |
Docs found: AGENTS.mdCONTRIBUTING.mdREADME.mddocs/link-checker/README.MD
Package
Cargo.toml — turborepo-crates, 0 declared dependencies.
CI & config entrypoints
README.md— Repository readmeAGENTS.md— Agent instructions.github/workflows/docs-alias-failure-notification.yml— GitHub Actions workflow.github/workflows/lint-pr-title.yml— GitHub Actions workflow.github/workflows/lint.yml— GitHub Actions workflow.github/workflows/lsp.yml— GitHub Actions workflow.github/workflows/pr-clean-caches.yml— GitHub Actions workflow.github/workflows/release-review-gate.yml— GitHub Actions workflow.github/workflows/test-js-packages.yml— GitHub Actions workflow.github/workflows/turborepo-compare-cache-item.yml— GitHub Actions workflow
Structural health signals
Average score 5.4/10 across 96 analyzed source files; 89 hotspots surfaced.
crates/turborepo-repository/src/go.rs— 1390 lines, score 4 (Large file, Deep nesting)crates/turborepo-cache/src/http.rs— 1335 lines, score 4 (Large file, Deep nesting)crates/turborepo-filewatch/src/package_watcher.rs— 1324 lines, score 4 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
2540ee1d740b2026-10-02 — chore: Release Turborepo 2.11.7 (#14357)3ce82f57d27f2026-10-02 — fix: Ignore Vercel OIDC token rotation in .env.local cache inputs (#14356)8cc3cce307052026-10-01 — chore: Update with-vite-module-federation example (#14349)41387de0cdd22026-10-01 — fix: Pass SDKROOT through to repository tasks (#14353)3a2072cad9ea2026-10-01 — chore: Release Turborepo 2.11.6 (#14352)