Overview
Purpose and Scope
Turborepo is the build system this repository ships for JavaScript and TypeScript workspaces. The root README introduces it as a high-performance build system written in Rust, while the documentation introduction explains the product goal more directly: make monorepos and even single-package workspaces faster by optimizing the tasks teams already run. This page orients new readers to the problem Turborepo solves, the main concepts they will encounter, and the documentation structure represented in the repository. It is intentionally broad: use it to decide where to start, then follow the more focused pages for installation, configuration, commands, caching, and repository design.
Sources: README.md, apps/docs/content/docs/index.mdx
The central reader problem is scale. A small repository may have a few scripts, but a mature monorepo can contain many applications and packages, each with its own build, lint, test, and type-check steps. The documentation introduction calls out that a single monorepo can have thousands of tasks to execute, and that slow feedback loops directly affect how quickly teams can deliver quality software. Turborepo addresses that by keeping the developer workflow close to existing npm ecosystem conventions instead of requiring teams to rewrite every build step around a new task runner.
Sources: apps/docs/content/docs/index.mdx
What Turborepo Solves
Turborepo treats repository work as a set of tasks that can be scheduled, cached, and replayed. A task is usually an existing package.json script, such as a build, lint, or test command. The documentation emphasizes that Turborepo can be adopted incrementally because it uses scripts teams have already written, dependencies they have already declared, and a single turbo.json file to describe task behavior. That design matters: the first step for most teams is not a migration away from their package manager or framework, but adding a coordination layer that understands how work in the repository relates.
Sources: apps/docs/content/docs/index.mdx
The monorepo solution described by the docs has two major performance levers. First, Remote Cache stores task results so the same work does not need to run repeatedly in continuous integration or across machines. Second, Turborepo schedules tasks for maximum speed by parallelizing work across available cores while respecting the relationships between packages and tasks. In practice, that means the tool can decide when a package needs to be built before another package is tested, while still running independent work concurrently. The result is a faster feedback loop without abandoning familiar project scripts.
Sources: apps/docs/content/docs/index.mdx
Turborepo is also not limited to the largest workspaces. The introduction explicitly says it is designed for scaling monorepos and also improves workflows in single-package workspaces. That is an important framing for repository owners: the same primitives used to accelerate a large multi-application workspace can also simplify task caching and command consistency in a smaller project. The adoption path can therefore begin with one or two high-value tasks, then expand as teams gain confidence in task dependencies, outputs, environment handling, and remote cache behavior.
Sources: apps/docs/content/docs/index.mdx
Core Primitives
The first primitive is the package or workspace. Turborepo leans on npm ecosystem conventions and can be used with package managers such as npm, yarn, and pnpm. Package manager configuration and dependency declarations remain the source of truth for what packages exist and how they depend on each other. Turborepo adds scheduling and caching around that graph rather than replacing it. Readers who are new to the project should understand that this makes the repository layout, package manifests, and package manager lockfile important inputs to how tasks are selected and ordered.
Sources: apps/docs/content/docs/index.mdx
The second primitive is the task. A task is the unit of work Turborepo runs, and the docs describe those tasks as the scripts already present in package.json. The turbo.json file supplies Turborepo-specific defaults such as dependencies between tasks, cache behavior, and outputs that should be saved or restored. This distinction is the key to a clean configuration: package scripts continue to express how an individual package builds or tests itself, while turbo.json expresses how those scripts should behave across the repository as a coordinated system.
Sources: apps/docs/content/docs/index.mdx
The third primitive is caching, including Remote Cache. Local caching avoids repeating work on the same machine, while Remote Cache allows task artifacts to be shared across CI jobs and developers when the same inputs produce the same result. The overview documentation highlights Remote Cache as the reason CI does not need to do the same work twice. When reading the rest of the wiki, treat caching as a correctness-sensitive optimization: task inputs, outputs, dependency ordering, and environment variables all affect whether a previous result can be reused safely.
Sources: apps/docs/content/docs/index.mdx
Documentation Structure
The repository documentation is organized as a learning path rather than a flat command index. The docs metadata lists the main sections in order: the introduction, getting started, crafting your repository, reference, core concepts, guides, community, support policy, glossary, and changelog. That ordering is useful for readers because Turborepo combines conceptual modeling with practical command usage. Start with getting started and installation when you need a running project, move to core concepts when you need to reason about task graphs and caching, and use reference pages when you need exact command or configuration behavior.
Sources: apps/docs/content/docs/meta.json
The crafting-your-repository and guides sections are especially important once a repository has more than one team or application. The introduction page states that Turborepo is a lightweight approach to optimizing the tasks a repository already needs to run, but lightweight does not mean configuration-free. Teams still need to choose package boundaries, decide which task outputs are cacheable, separate long-running development servers from finite build tasks, and build CI flows that use the same task model developers use locally. The broader docs structure exists to help make those design choices explicit.
Sources: apps/docs/content/docs/index.mdx, apps/docs/content/docs/meta.json
The reference section should be treated as the authoritative place for exact names and options, while this overview explains the mental model. Official reference pages describe command families such as turbo run, option precedence across configuration, environment variables, and flags, and remote cache APIs for compatible cache servers. Those details are intentionally downstream of the introduction: first learn that Turborepo coordinates scripts using a task graph and cache, then use the reference pages to tune command invocations, environment-specific behavior, and integration points.
Sources: apps/docs/content/docs/meta.json
System-to-Code Mapping
| Source path | What it represents | Why it matters |
|---|---|---|
README.md | Repository-level project introduction, community links, security contact, and public package badges. | Establishes Turborepo as a Vercel project, describes it as a Rust-written build system for JavaScript and TypeScript, and points readers to the public site and community. |
apps/docs/content/docs/index.mdx | First-party documentation introduction. | Defines the monorepo scaling problem, the Turborepo solution, incremental adoption, Remote Cache, task scheduling, package manager compatibility, and reader-facing navigation intent. |
apps/docs/content/docs/meta.json | Documentation section ordering. | Shows the major docs surfaces readers will navigate: getting started, repository crafting, reference, core concepts, guides, community, support policy, glossary, and changelog. |
Sources: README.md, apps/docs/content/docs/index.mdx, apps/docs/content/docs/meta.json
The repository exposes several public surfaces even from this small set of overview files. The README points to the turbo npm package badge and the public site, which signals the CLI as the user-facing entry point. The docs introduction points to turbo.json, package.json scripts, package manager conventions, and Remote Cache as the core configuration and runtime surfaces. The metadata file exposes the documentation taxonomy that the rest of this OpenWiki mirrors. Together, those files show a project that is both a CLI product and a documentation-led developer platform for monorepo workflows.
Sources: README.md, apps/docs/content/docs/index.mdx, apps/docs/content/docs/meta.json
Execution Flow
A typical adoption flow starts by identifying existing scripts that are expensive or repeatedly run, such as builds, tests, linting, and type checks. Turborepo then uses a turbo.json configuration to describe how those tasks relate across packages. When a user invokes Turborepo, the system can schedule eligible work in parallel, respect dependencies that must run first, and use cached artifacts when inputs match prior work. The documentation introduction’s phrase “add it to any repository in just a few minutes” should be read in that context: the first working setup can be small, but the model scales as configuration becomes more precise.
Sources: apps/docs/content/docs/index.mdx
For teams, the most important operational outcome is consistency between local development and CI. If developers and CI run the same task names through Turborepo, the repository gains a shared language for performance and correctness. Remote Cache then becomes a shared artifact layer instead of a machine-local optimization. The README’s community and security sections also show the expected support boundaries: general questions and project sharing belong in public community channels, while suspected vulnerabilities should be disclosed privately through Vercel’s security process rather than opened as public issues.
Sources: README.md, apps/docs/content/docs/index.mdx
Relevant Source Files
README.md— Root project summary for Turborepo, including the high-performance build-system description, Rust implementation note, public website link, community channels, showcase, updates, and security disclosure guidance.apps/docs/content/docs/index.mdx— Main documentation introduction for Turborepo, including the monorepo scaling problem, task scheduling, Remote Cache, incremental adoption,package.jsonscripts,turbo.json, and package manager compatibility.apps/docs/content/docs/meta.json— Documentation navigation metadata that defines the major top-level sections used by the docs and mirrored by this wiki outline.
Next Steps
If you are evaluating Turborepo for the first time, read the Getting Started and Installation pages next so you can run the CLI in a real workspace. If you already have a repository and want to model work correctly, move to the Core Concepts pages for tasks, package graphs, caching, Remote Cache, and environment variables. If you are designing a production monorepo, continue into Crafting Your Repository for structure, dependency management, task configuration, development workflows, CI, code generation, and publishing guidance. Keep the Reference section nearby when you need exact turbo.json fields, command flags, or system environment variable behavior.
Sources: apps/docs/content/docs/meta.json