turbo.json Configuration

Purpose and Scope

Use this page when you need to decide what belongs in a Turborepo configuration file, what should stay in the surrounding environment, and what should be overridden only for one command. The repository documentation describes the root configuration file as the primary way to configure the behavior of the command runner for a Workspace, with Package Configurations available when a package needs more granular behavior. In practical terms, this page is the reference for repository-wide defaults, task definitions, cache behavior, environment variable hashing, terminal presentation, and forward-looking flags. Sources: apps/docs/content/docs/reference/configuration.mdx, apps/docs/content/docs/reference/options-overview.mdx

Turborepo treats configuration as one layer in a three-layer control model. Defaults live in the configuration file, system environment variables provide per-environment overrides, and command-line flags provide per-invocation overrides. The options overview explicitly orders those strategies by precedence and recommends using configuration for stable defaults, environment variables for differences between local machines and continuous integration, and flags when a developer or pipeline needs a one-off behavior. That distinction matters because a confusing configuration usually comes from putting temporary behavior, such as forcing work to rerun, into a permanent repository file. Sources: apps/docs/content/docs/reference/options-overview.mdx

A valid configuration can be used in both multi-package and single-package workspaces. In a monorepo, the file coordinates package tasks, dependency-aware execution, outputs, and shared environment rules across packages. In a single-package workspace, the same concepts still provide caching and parallelization benefits, but package-scoped task names such as package task selectors are not useful because there is only one package to address. The documentation also supports editor validation through a schema key, with versioned web schemas and a schema file distributed from the installed package for local editor integrations.

Relevant Source Files

• apps/docs/content/docs/reference/configuration.mdx — Primary reference for root and package-level configuration fields, including global options, environment handling, task options, remote cache settings, and future flags.
• apps/docs/content/docs/reference/options-overview.mdx — Maps configuration keys to equivalent command flags and system environment variables, and documents precedence between the three mechanisms.
• apps/docs/content/blog/free-vercel-remote-cache.mdx — Provides the current reader-facing context for Vercel Remote Cache, including free remote caching for repositories linked to Vercel and the token/team setup for other CI providers.
• apps/docs/content/blog/joining-vercel.mdx — Records the project context that Turborepo joined Vercel and that zero-configuration remote caching through Vercel became part of the public story.
• apps/docs/content/docs/guides/ci-vendors/github-actions.mdx — Shows a concrete workflow that runs package scripts backed by Turborepo and demonstrates a root configuration with task outputs and dependencies.
• apps/docs/content/docs/guides/ci-vendors/vercel.mdx — Describes Vercel’s zero-configuration integration and how Vercel projects are preconfigured to use Vercel Remote Cache.

Configuration File Location and Schema

Place the repository-level configuration at the Workspace root. The reference says the file controls the behavior of the command runner from that root location, and it also allows a commented variant when teams want comments with editor support. A root file usually starts with a schema declaration so editors can validate field names, value shapes, and task configuration as the file evolves. The editor integration documentation recommends a versioned schema URL for installed versions beginning with the documented release line, while older or simpler setups can use the unversioned schema. Sources: apps/docs/content/docs/reference/configuration.mdx

{
  "$schema": "https://turborepo.dev/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    }
  }
}

The schema key is not a runtime task rule by itself, but it is an important maintenance feature. It keeps configuration review focused on intended behavior instead of typographical mistakes, especially when teams use fields with similar names such as hashed environment variables and passthrough environment variables. If a package-level configuration extends the root configuration, its schema path may need to point back to the root installation directory, because the schema can also be sourced from the installed package. That workflow is especially useful in editors that resolve local files more reliably than network resources.

Global Options

Global options affect the whole Workspace unless a more specific package configuration or invocation changes behavior. The extension mechanism is for package-level configuration: a package configuration can inherit from the root by beginning its extension list with the documented root marker, and it can then extend other shared package configurations. The root file itself ignores that extension field, so do not use it as a root-level composition mechanism. Use it when a package needs to add or refine task behavior without duplicating the entire repository configuration. Sources: apps/docs/content/docs/reference/configuration.mdx

Global dependency globs add files to every task hash. The reference emphasizes the consequence: if any matching file changes, every task misses cache. That is the correct tool for files that truly affect all work, such as a shared TypeScript configuration or another repository-wide tool configuration. It is the wrong tool for package-local inputs, because it would make unrelated packages lose cache unnecessarily. Globs are relative to the configuration file location, must stay inside the repository’s source-control root, and are not automatically copied by pruning unless the future flag for including global files is enabled. Sources: apps/docs/content/docs/reference/configuration.mdx

Global environment fields are split by purpose. Hashed environment variables belong in the global hash when a value changes the correctness of task outputs for every task. Passthrough environment variables are made available to tasks but do not, by themselves, affect cache keys. That distinction prevents secrets such as cloud credentials from becoming cache invalidators while still allowing task processes to read them. The reference warns that passthrough values must also be listed in hashed environment fields if changes in those values should cause cache misses. Sources: apps/docs/content/docs/reference/configuration.mdx

Several global fields tune invocation behavior rather than task correctness. The terminal interface can be set to a streaming log mode or an interactive terminal UI. The update notifier can be disabled for repositories that want quieter output. Concurrency limits how much work the runner schedules at once, which is useful when CI machines have fixed CPU or memory budgets. These settings are good examples of repository defaults: they express how the team usually wants the tool to behave, while still leaving room for an environment variable or command flag when one machine needs different behavior. Sources: apps/docs/content/docs/reference/configuration.mdx, apps/docs/content/docs/reference/options-overview.mdx

Task Configuration

The tasks map is the core of the configuration file because it tells Turborepo how package scripts relate to each other, which files they produce, what they consume, and whether caching is safe. A task name usually corresponds to a script name in package manifests. In the GitHub Actions guide, the root package defines build and test scripts that call the command runner, and the configuration declares build outputs plus a dependency from build to upstream package builds. That is the canonical shape: scripts remain package-manager scripts, while the configuration supplies orchestration metadata. Sources: apps/docs/content/docs/guides/ci-vendors/github-actions.mdx, apps/docs/content/docs/reference/configuration.mdx

The dependency list explains order and graph traversal. A caret dependency means the same task should run in dependency packages before the current package task. A plain task dependency can express work within the same package, and package-qualified task names can target specific package tasks in multi-package workspaces. Outputs identify files and directories that should be restored on a cache hit. Inputs narrow or expand the file set that participates in hashing. Cache can be disabled for tasks that should always execute, and log behavior can be adjusted when teams need full, summarized, or quieter task output.

Persistent, interactive, interruptible, and companion task settings are for development workflows rather than one-shot builds. A persistent task represents a long-running process such as a development server, so it should not be treated like a finite build step. An interruptible task can be restarted when dependencies change during watch-style workflows. Interactive tasks are allowed to receive input from the terminal UI. Companion tasks make it possible to run supporting work alongside another task. These fields should be used deliberately, because a persistent or interactive process has different scheduling expectations from a deterministic build or test command.

Environment and Cache Semantics

The most important configuration design rule is to separate correctness from convenience. Files and environment variables that change task results should be included in hashes, either globally or for a specific task. Values that are only needed at runtime should be passed through without becoming hash inputs. This is why the configuration reference has both hashed and passthrough environment fields, and why the options overview also points readers to system environment variables for changing command behavior. Correctly modeling this distinction makes cache hits trustworthy instead of merely frequent. Sources: apps/docs/content/docs/reference/configuration.mdx, apps/docs/content/docs/reference/options-overview.mdx

Remote caching is configured by a mix of repository defaults, environment variables, and platform integration. The options overview maps remote cache timeout, upload timeout, preflight behavior, base API URL, and signature key across configuration and environment variables. Vercel’s current documentation says commands on Vercel are automatically configured to use Vercel Remote Cache, while other CI providers authenticate with token and team environment variables. The older project announcement also explains why Vercel remote caching is part of Turborepo’s public surface. Sources: apps/docs/content/docs/reference/options-overview.mdx, apps/docs/content/blog/free-vercel-remote-cache.mdx, apps/docs/content/blog/joining-vercel.mdx, apps/docs/content/docs/guides/ci-vendors/vercel.mdx

{
  "globalDependencies": ["tsconfig.json"],
  "globalEnv": ["NODE_ENV"],
  "globalPassThroughEnv": ["GITHUB_TOKEN"],
  "remoteCache": {
    "timeout": 30,
    "uploadTimeout": 60,
    "preflight": true
  }
}

Compact Field Reference

CI and Platform Usage

A CI workflow should keep the configuration stable and move environment-specific details into the CI environment. The GitHub Actions guide demonstrates a root configuration with build outputs, dependency-aware build ordering, and scripts that invoke build and test through the package manager. Remote caching is then enabled by setting token and team values in the workflow environment instead of hardcoding credentials into the repository file. For npm workflows, the guide also shows a remote-only environment variable in the commented setup, underscoring that per-provider differences belong in CI configuration. Sources: apps/docs/content/docs/guides/ci-vendors/github-actions.mdx, apps/docs/content/blog/free-vercel-remote-cache.mdx

On Vercel, the integration is intentionally lighter. The Vercel guide says the platform automatically understands the monorepo after import and preconfigures projects to use Vercel Remote Cache. That means many repositories can keep remote cache configuration minimal and focus the configuration file on task graph correctness, outputs, inputs, and environment hashing. For other providers, keep the same task configuration and add the documented authentication variables in the provider’s secret or variable store. This split keeps local development, Vercel deployments, and other CI runs aligned without duplicating task semantics. Sources: apps/docs/content/docs/guides/ci-vendors/vercel.mdx, apps/docs/content/blog/free-vercel-remote-cache.mdx

Implementation Checklist and Next Steps

Start with a small configuration: add a schema, define the tasks that correspond to package scripts, declare dependency relationships, and list outputs for cacheable build artifacts. Then add global dependencies only for files that truly influence every task. Next, audit environment variables and decide which values affect outputs and which are runtime-only. Finally, decide whether any repository-wide terminal, concurrency, notification, remote cache, or future-flag defaults should be committed. When reviewing changes, ask whether the field belongs in configuration, in the system environment, or as a one-time command flag.

Read the package configuration reference when one package needs behavior that differs from the root. Read the task configuration guide when designing dependencies, inputs, outputs, or persistent development tasks. Read the system environment variables reference when a setting should vary between local development, GitHub Actions, Vercel, or another provider. Read the glob syntax reference before using broad global dependencies or outputs, because a single overly broad pattern can make every task miss cache or restore files that should not be treated as build artifacts.