Reference Overview
Turborepo’s reference section is the place to use when you already understand the broad workflow and need exact names, command families, configuration areas, and package entry points. The landing page describes the reference as an API reference for Turborepo and summarizes it as an entry point for configuration, CLI commands, and packages. That structure matters because Turborepo is used from several surfaces at once: repository configuration, terminal commands, environment variables, file glob patterns, and companion packages that extend or scaffold workspaces. This overview helps you choose the right reference page before you start editing a configuration file or composing a command.
Sources: apps/docs/content/docs/reference/index.mdx, apps/docs/content/docs/reference/meta.json
Purpose and Scope
Use this page as a map of the reference documentation rather than as a replacement for the deeper command pages. The reference landing page groups material into Configuration, Commands, Packages, and a flag syntax area. The navigation metadata also shows the order in which those pages appear in the documentation sidebar, including options-overview alongside the configuration references and the command references. In practice, that means you should start here when you are deciding whether a behavior belongs in the root configuration, a package-specific configuration, an environment variable, a global command flag, or a package that you install into the workspace.
The most important distinction is between persistent repository behavior and one-off command behavior. Configuration pages cover durable settings that live with the repository, such as task definitions, package-level overrides, system environment variable behavior, and glob syntax used to describe files. Command pages cover terminal operations such as running tasks, watching files, pruning a workspace for deployment, querying the monorepo graph, managing remote cache authentication, and finding the turbo binary. Package pages cover installable tools and integrations such as create-turbo, eslint-config-turbo, eslint-plugin-turbo, turbo-ignore, turbo-codemod, and @turbo/gen.
Sources: apps/docs/content/docs/reference/index.mdx, apps/docs/content/docs/reference/meta.json
Relevant Source Files
- apps/docs/content/docs/reference/index.mdx — Defines the reference landing page front matter, related links, section headings, and card-based entries for configuration, commands, packages, and the start of flag syntax coverage.
- apps/docs/content/docs/reference/meta.json — Defines the API reference navigation order, including configuration pages, command pages, and package pages exposed in the documentation sidebar.
System-to-Code Mapping
The source mapping is intentionally small because this page is a documentation index. The content file is the reader-facing source of truth for the overview: it sets the title, description, product, type, summary, and related pages, then renders cards for the major reference areas. The metadata file is the navigation source of truth: it names the section title as API reference and lists the pages in the order users encounter them. When these files differ in emphasis, read them together: the content page explains how a reader should think about the reference, while the metadata file shows the full menu of reference pages available under that section.
The Configuration group in the landing page includes configuring turbo.json, package configurations, system environment variables, and file glob specification. The metadata extends that cluster with options-overview, which is the natural destination when a reader is looking for global flags and common option syntax rather than a specific command. This separation keeps long-lived repository semantics away from terminal-only invocation details. A reader troubleshooting whether an input pattern belongs in a task definition should go to configuration or globs; a reader deciding how to pass a flag for a single run should go to options-overview or the relevant command page.
Sources: apps/docs/content/docs/reference/index.mdx, apps/docs/content/docs/reference/meta.json
| Area | Reference entries visible in the source | Reader question answered |
|---|---|---|
| Configuration | configuration, package-configurations, system-environment-variables, globs, options-overview | How do I define durable repository behavior and shared option conventions? |
| Commands | run, watch, prune, boundaries, ls, query, devtools, docs, generate, scan, login, logout, link, unlink, bin, info, telemetry | Which terminal command should I use for this operation? |
| Packages | create-turbo, eslint-config-turbo, eslint-plugin-turbo, turbo-ignore, turbo-codemod, turbo-gen | Which installable package supports this workflow? |
Command Families
The command list in the landing page and metadata covers several practical families. Execution commands include run and watch: run is described as running tasks using turbo, while watch is described as a dependency-aware, single-process task watcher. Repository-shaping commands include prune, which creates partial monorepos for target workspaces, and boundaries, which enforces best practices in a monorepo. Discovery commands include ls for listing packages, query for running GraphQL queries against the monorepo, docs for searching documentation, bin for locating the turbo binary, info for diagnostic information, and devtools for the associated developer tooling page listed in metadata.
Remote cache and account-related commands form another family. The landing page includes login and logout for authenticating with a Remote Cache provider, link for connecting a repository to Remote Cache, and unlink for disconnecting it. These entries are separate from run because authentication and repository linking are setup operations, not task execution operations. The deprecated scan entry is still present in the reference, marked as deprecated on the landing page, which is a signal that readers should avoid designing new workflows around it and should verify the replacement path in the more specific reference page.
Sources: apps/docs/content/docs/reference/index.mdx, apps/docs/content/docs/reference/meta.json
Configuration, Global Flags, and Flag Syntax
The reference overview points to configuration topics before commands because configuration determines how most commands behave. The configuring turbo.json page is the durable repository contract for turbo behavior. Package Configurations explain package-specific settings, which are important when a workspace needs a local exception without changing every package. System environment variables change turbo behavior outside the configuration file, and File glob specification explains how file sets are expressed. Together, these pages answer what the repository declares, what a package overrides, what the process environment changes, and how file matching syntax is interpreted.
Global flags and flag syntax are represented by the reference structure rather than by a long list on the overview itself. The content front matter links to options-overview as a related page, and the metadata places options-overview with the configuration-oriented reference entries. The landing page also begins a Flag syntax section after the Packages group. The practical reading order is to use the command page when a flag is command-specific, use options-overview when the option applies across commands or explains common syntax, and use the configuration pages when the behavior should be checked into the repository instead of supplied at the terminal.
Sources: apps/docs/content/docs/reference/index.mdx, apps/docs/content/docs/reference/meta.json
Package Reference Surfaces
The Packages group documents installable surfaces that complement the core turbo command. create-turbo is the starting package for creating a new Turborepo from an example. eslint-config-turbo and eslint-plugin-turbo are related ESLint integrations; the landing page describes the config package as helping find environment variables not listed in turbo.json, and the metadata includes both the config and plugin reference pages. turbo-ignore is listed as deprecated, with the landing page directing readers to use turbo query affected instead. turbo-codemod and turbo-gen appear in the metadata, with @turbo/gen described on the landing page as type definitions for Turborepo generators.
This package grouping is useful because not every reference question is a command-line question. If you are scaffolding a repository, you need the create-turbo package page. If you are enforcing environment variable declarations through linting, you need the ESLint package references. If you are generating new apps or packages, you need the generate command for the CLI workflow and the @turbo/gen package for generator types. If you are modernizing a repository, turbo-codemod belongs in the package reference, while deprecated turbo-ignore workflows should be compared with the query command and affected queries.
Sources: apps/docs/content/docs/reference/index.mdx, apps/docs/content/docs/reference/meta.json
Choosing the Right Reference Page
A good way to navigate the reference is to start with the artifact you plan to change. If you are editing a repository file, begin with configuration, package-configurations, globs, or system-environment-variables. If you are typing a terminal command, begin with run, watch, prune, query, generate, or the remote cache commands. If you are adding a dependency to package.json, begin with the package reference for create-turbo, the ESLint packages, turbo-codemod, or turbo-gen. This artifact-first approach prevents common mistakes such as encoding a one-time command flag into shared configuration or using a deprecated helper where a newer command exists.
For task execution, the run reference is the central page because it explains the command used to run tasks. For iterative local development, watch has its own page because its behavior is dependency-aware and single-process. For deployment and container preparation, prune is the relevant page because it creates partial monorepos for target workspaces. For impact analysis and selecting affected work, query is the page to read because it is explicitly documented as running GraphQL queries against the monorepo. For Remote Cache setup, use login, logout, link, and unlink before focusing on cache behavior during task execution.
Sources: apps/docs/content/docs/reference/index.mdx, apps/docs/content/docs/reference/meta.json
Compact Reference
| Need | Start with | Why |
|---|---|---|
| Configure turbo behavior | configuration | Defines durable behavior for the repository. |
| Override behavior in one package | package-configurations | Describes package-specific configuration. |
| Understand file matching | globs | Defines file glob specification. |
| Change behavior from the environment | system-environment-variables | Covers system-level environment variables. |
| Understand common flags | options-overview | Listed in reference navigation and related from the overview. |
| Run tasks | run | Described as running tasks using turbo. |
| Re-run work during development | watch | Described as a dependency-aware watcher. |
| Prepare a partial monorepo | prune | Described as creating partial monorepos for targets. |
| Query repository structure | query | Described as GraphQL queries against the monorepo. |
| Scaffold examples | create-turbo | Described as getting started with an example. |
| Add generator types | turbo-gen | Covers @turbo/gen in the package reference. |
Next Steps
After this overview, pick the most specific page that matches the action you are taking. Read turbo.json Configuration before changing task behavior, Glob Syntax before writing file patterns, and System Environment Variables before relying on process-level settings. Read turbo run before designing task execution in CI, turbo watch before local watcher workflows, turbo prune before Docker or deployment pruning, and turbo query before affected-work automation. For ecosystem packages, continue to Create a New Monorepo, ESLint Packages, @turbo/gen and turbo generate, or @turbo/codemod depending on whether you are scaffolding, linting, generating, or migrating.
Sources: apps/docs/content/docs/reference/index.mdx, apps/docs/content/docs/reference/meta.json