@turbo/types/src/types/config-v2.ts

Turborepo types

export type OutputLogs =
  | "full"
  | "none"
  | "hash-only"
  | "new-only"
  | "errors-only";
export type EnvMode = "loose" | "strict";
export type UI = "tui" | "stream" | "stream-with-experimental-timestamps";
/**
 * This is a relative Unix-style path (e.g. `./src/index.ts` or `src/index.ts`).  Absolute paths (e.g. `/tmp/foo`) are not valid.
 */
export type RelativeUnixPath = string;
export type EnvWildcard = string;

export interface BaseSchema {
  /** @defaultValue `https://turborepo.dev/schema.v2.json` */
  $schema?: string;
  /**
   * An object representing the task dependency graph of your project. turbo interprets
   * these conventions to schedule, execute, and cache the outputs of tasks in
   * your project.
   *
   * Documentation: https://turborepo.dev/docs/reference/configuration#tasks
   *
   * @defaultValue `{}`
   */

  // eslint-disable-next-line @typescript-eslint/consistent-indexed-object-style -- it's more readable to specify a name for the key
  tasks: {
    /**
     * The name of a task that can be executed by turbo. If turbo finds a workspace
     * package with a package.json scripts object with a matching key, it will apply the
     * pipeline task configuration to that npm script during execution.
     */
    [script: string]: Pipeline;
  };
}

/** A `turbo.json` file in a package in the monorepo (not the root) */
export interface WorkspaceSchema extends BaseSchema {
  /**
   * This key is only available in Workspace Configs
   * and cannot be used in your root turbo.json.
   *
   * Tells turbo to extend your root `turbo.json`
   * and overrides with the keys provided
   * in your Workspace Configs.
   *
   * Currently, only the "//" value is allowed.
   *
   * @defaultValue `["//"]`
   */
  extends: Array<string>;
  /**
   * Used to tag a package for boundaries rules. Boundaries rules can restrict
   * which packages a tag group can import or be imported by.
   */
  tags?: Array<string>;
  /**
   * Configuration for `turbo boundaries` that is specific to this package
   */
  boundaries?: BoundariesConfig;
}

export interface RootSchema extends BaseSchema {
  /**
   * A list of globs to include in the set of implicit global hash dependencies.
   *
   * The contents of these files will be included in the global hashing
   * algorithm and affect the hashes of all tasks.
   *
   * This is useful for busting the cache based on:
   *
   * - .env files (not in Git)
   *
   * - any root level file that impacts package tasks
   * that are not represented in the traditional dependency graph
   * (e.g. a root tsconfig.json, jest.config.ts, .eslintrc, etc.)
   *
   * Documentation: https://turborepo.dev/docs/reference/configuration#globaldependencies
   *
   * @defaultValue `[]`
   */
  globalDependencies?: Array<string>;

  /**
   * A list of environment variables for implicit global hash dependencies.
   *
   * The variables included in this list will affect all task hashes.
   *
   * Documentation: https://turborepo.dev/docs/reference/configuration#globalenv
   *
   * @defaultValue `[]`
   */
  globalEnv?: Array<EnvWildcard>;

  /**
   * An allowlist of environment variables that should be made to all tasks, but
   * should not contribute to the task's cache key, e.g. `AWS_SECRET_KEY`.
   *
   * Documentation: https://turborepo.dev/docs/reference/configuration#globalpassthroughenv
   *
   * @defaultValue `null`
   */
  globalPassThroughEnv?: null | Array<EnvWildcard>;

  /**
   * Configuration options that control how turbo interfaces with the remote cache.
   *
   * Documentation: https://turborepo.dev/docs/core-concepts/remote-caching
   *
   * @defaultValue `{}`
   */
  remoteCache?: RemoteCache;

  /**
   * Enable use of the UI for `turbo`.
   *
   * Documentation: https://turborepo.dev/docs/reference/configuration#ui
   *
   * @defaultValue `"stream"`
   */
  ui?: UI;

  /**
   * Set/limit the maximum concurrency for task execution. Must be an integer greater than or equal to `1` or a percentage value like `50%`.
   *
   *  - Use `1` to force serial execution (one task at a time).
   *  - Use `100%` to use all available logical processors.
   *
   * Documentation: https://turborepo.dev/docs/reference/configuration#concurrency
   *
   * @defaultValue `"10"`
   */
  concurrency?: string;

  /**
   * Disable package manager declaration checks in root `package.json`.
   *
   * This is highly discouraged as it leaves `turbo` dependent on system
   * configuration to infer the correct package manager.
   *
   * Some turbo features are disabled if this is set to true.
   *
   * @defaultValue `false`
   */
  dangerouslyDisablePackageManagerCheck?: boolean;

  /**
   * Specify the filesystem cache directory.
   *
   * Documentation: https://turborepo.dev/docs/reference/configuration#cachedir
   *
   * @defaultValue `".turbo/cache"`
   */
  cacheDir?: RelativeUnixPath;

  /**
   * Maximum age of local cache entries before automatic eviction.
   *
   * Accepts a human-readable duration string (e.g. `"7d"`, `"24h"`, `"2w"`).
   * Set to `"0"` to disable eviction (the default).
   * Entries older than this value are removed at the start of each run.
   *
   * @defaultValue `"0"`
   */
  cacheMaxAge?: string;

  /**
   * Maximum total size of the local filesystem cache.
   *
   * Accepts a human-readable size string (e.g. `"10GB"`, `"500MB"`).
   * When exceeded, the oldest entries are evicted until the cache is
   * under the limit. Set to `"0"` to disable (the default).
   *
   * @defaultValue `"0"`
   */
  cacheMaxSize?: string;

  /**
   * Deprecated: The daemon is no longer used for `turbo run` and this option will be removed in version 3.0.
   *
   * Documentation: https://turborepo.dev/docs/reference/configuration#daemon
   *
   * @defaultValue `false`
   */
  daemon?: boolean;

  /**
   * Turborepo's Environment Modes allow you to control which environment variables are available to a task at runtime:
   *
   * - `"strict"`: Filter environment variables to only those that are specified in the `env` and `globalEnv` keys in `turbo.json`.
   * - `"loose"`: Allow all environment variables for the process to be available.
   *
   * Documentation: https://turborepo.dev/docs/reference/configuration#envmode
   *
   * @defaultValue `"strict"`
   */
  envMode?: EnvMode;

  /**
   * Configuration for `turbo boundaries`. Allows users to restrict a package's dependencies and dependents
   */
  boundaries?: RootBoundariesConfig;

  /**
   * When set to `true`, disables the update notification that appears when a new version of `turbo` is available.
   *
   * Documentation: https://turborepo.dev/docs/reference/configuration#noupdatenotifier
   *
   * @defaultValue `false`
   */
  noUpdateNotifier?: boolean;

  /**
   * Global configuration block.
   *
   * When `futureFlags.globalConfiguration` is enabled, global settings
   * like `inputs`, `env`, `ui`, etc. are placed here instead of at the
   * top level.
   */
  global?: GlobalConfig;

  /**
   * Opt into breaking changes prior to major releases, experimental features, and beta features.
   *
   * @defaultValue `{}`
   */
  futureFlags?: FutureFlags;
}

export interface FutureFlags {
  /**
   * When using `outputLogs: "errors-only"`, show task hashes when tasks
   * complete successfully. This provides visibility into which tasks are
   * running without showing full output logs.
   *
   * @defaultValue `false`
   */
  errorsOnlyShowHash?: boolean;
  /**
   * Enable experimental OpenTelemetry exporter support.
   *
   * When enabled, Turborepo will honor the `experimentalObservability`
   * configuration block (if present) to send run summaries to an
   * observability backend.
   *
   * @defaultValue `false`
   */
  experimentalObservability?: boolean;
  /**
   * Enforce a minimum length of 32 bytes for
   * `TURBO_REMOTE_CACHE_SIGNATURE_KEY` when `remoteCache.signature` is
   * enabled. Short keys weaken the HMAC-SHA256 signature, making brute-force
   * tag collision feasible.
   *
   * @defaultValue `false`
   */
  longerSignatureKey?: boolean;
  /**
   * Use task-level `inputs` globs to determine which tasks are affected by
   * changed files when running with `--affected`. When enabled, only tasks
   * whose declared inputs match the changed files are selected, rather than
   * selecting all tasks in changed packages.
   *
   * @defaultValue `false`
   */
  affectedUsingTaskInputs?: boolean;
  /**
   * When GitHub Actions reports a base branch that is not available as a
   * local ref, fall back to `origin/<branch>`. This supports detached
   * checkouts where only remote-tracking refs are present.
   *
   * @defaultValue `false`
   */
  githubActionsRemoteBaseRefFallback?: boolean;
  /**
   * Use task-level `inputs` globs to determine which tasks to re-run when
   * files change in `turbo watch`. When enabled, only tasks whose declared
   * inputs match the changed files are re-executed, rather than re-running
   * all tasks in changed packages.
   *
   * @defaultValue `false`
   */
  watchUsingTaskInputs?: boolean;
  /**
   * Include files matching `globalDependencies` globs in the `turbo prune`
   * output. Without this flag, `globalDependencies` entries are preserved in
   * the pruned `turbo.json` but the actual files are not copied.
   *
   * @defaultValue `false`
   */
  pruneIncludesGlobalFiles?: boolean;
  /**
   * Resolve `--filter` at the task level instead of the package level.
   * Git-range filters (e.g. `--filter=[main]`) will match against task
   * `inputs` globs, and the `...` dependency/dependent syntax will
   * traverse the task graph in addition to the package graph.
   *
   * @defaultValue `false`
   */
  filterUsingTasks?: boolean;
  /**
   * Select requested task entrypoints according to whether the task resolves
   * a command in the repository. When any package can run a requested task,
   * packages without a command are skipped as entrypoints. Tasks with no
   * command anywhere remain available for graph-only orchestration.
   *
   * @defaultValue `false`
   */
  strictTaskEntrypointSelection?: boolean;
  /**
   * Move global configuration keys under a top-level `global` key.
   *
   * When enabled, keys like `globalDependencies`, `globalEnv`, `ui`,
   * etc. must be placed inside the `global` block with new names:
   * `globalDependencies` becomes `inputs`, `globalEnv` becomes `env`,
   * and `globalPassThroughEnv` becomes `passThroughEnv`.
   *
   * @defaultValue `false`
   */
  globalConfiguration?: boolean;
  /**
   * Treat the crates of a Cargo workspace as Turborepo packages.
   *
   * When enabled, Rust crates are discovered via `cargo metadata` and
   * participate in the package graph: they resolve in `--filter`
   * expressions, propagate `--affected`, and appear in `turbo query`.
   * Filtered builds execute each selected crate. Unfiltered builds prefer
   * entrypoints, falling back to libraries when no entrypoints exist.
   * Entrypoints also expose `run` and `dev`. The `test`, `check`, `lint`, and
   * `format` tasks are selectable per crate with `--filter`. An
   * unfiltered run executes one workspace-wide Cargo verification command;
   * filtered runs use the selected crates, or the workspace command when the
   * workspace package is selected directly.
   *
   * All crates implicitly register `build` and the verification tasks;
   * entrypoints with one binary also register `run` and `dev`. The workspace
   * package registers the verification tasks. Normal task definitions
   * configure or override these defaults, and package configuration can
   * exclude them with `extends: false`.
   *
   * Task caching uses Cargo-derived inputs and caches entrypoint build
   * deliverables. Library builds and formatting default to uncached. This
   * feature is experimental.
   *
   * @defaultValue `false`
   */
  experimentalCargoWorkspaces?: boolean;

  /**
   * Treat the members of a uv workspace as Turborepo packages.
   *
   * When enabled, Python packages are discovered from the root
   * `pyproject.toml`'s `[tool.uv.workspace]` members and participate in the
   * package graph: they resolve in `--filter` expressions, propagate
   * `--affected`, and appear in `turbo query`. Buildable packages register `build`
   * (`uv build --package`), and all packages register `format` and `check`.
   * Direct pytest declarations register ownership-scoped `test` tasks; the
   * user-named workspace package registers workspace-wide quality tasks.
   * External dependencies hash from `uv.lock` per
   * package, and `turbo prune` produces a reachability-pruned `uv.lock`
   * and root `pyproject.toml`. uv is the only supported Python package
   * manager. This feature is experimental.
   *
   * @defaultValue `false`
   */
  experimentalPythonWorkspaces?: boolean;
}

export interface GlobalConfig {
  /**
   * A list of globs for files that implicitly affect all tasks.
   *
   * These files are prepended to every task's `inputs` instead of being
   * included in the global hash. Tasks can exclude specific files via
   * negation globs (e.g. `"inputs": ["$TURBO_DEFAULT$", "!$TURBO_ROOT$/tsconfig.json"]`).
   *
   * Replaces `globalDependencies` when `futureFlags.globalConfiguration` is enabled.
   *
   * @defaultValue `[]`
   */
  inputs?: Array<string>;

  /**
   * A list of environment variables for implicit global hash dependencies.
   *
   * Replaces `globalEnv` when `futureFlags.globalConfiguration` is enabled.
   *
   * @defaultValue `[]`
   */
  env?: Array<EnvWildcard>;

  /**
   * An allowlist of environment variables that should be made to all tasks, but
   * should not contribute to the task's cache key.
   *
   * Replaces `globalPassThroughEnv` when `futureFlags.globalConfiguration` is enabled.
   *
   * @defaultValue `null`
   */
  passThroughEnv?: null | Array<EnvWildcard>;

  /**
   * Configuration options that control how turbo interfaces with the remote cache.
   *
   * Documentation: https://turborepo.dev/docs/core-concepts/remote-caching
   *
   * @defaultValue `{}`
   */
  remoteCache?: RemoteCache;

  /**
   * Enable use of the UI for `turbo`.
   *
   * Documentation: https://turborepo.dev/docs/reference/configuration#ui
   *
   * @defaultValue `"stream"`
   */
  ui?: UI;

  /**
   * Set/limit the maximum concurrency for task execution.
   *
   * Documentation: https://turborepo.dev/docs/reference/configuration#concurrency
   *
   * @defaultValue `"10"`
   */
  concurrency?: string;

  /**
   * Disable package manager declaration checks in root `package.json`.
   *
   * @defaultValue `false`
   */
  dangerouslyDisablePackageManagerCheck?: boolean;

  /**
   * Specify the filesystem cache directory.
   *
   * Documentation: https://turborepo.dev/docs/reference/configuration#cachedir
   *
   * @defaultValue `".turbo/cache"`
   */
  cacheDir?: RelativeUnixPath;

  /**
   * Maximum age of local cache entries before automatic eviction.
   *
   * Accepts a human-readable duration string (e.g. `"7d"`, `"24h"`, `"2w"`).
   * Set to `"0"` to disable eviction (the default).
   * Entries older than this value are removed at the start of each run.
   *
   * @defaultValue `"0"`
   */
  cacheMaxAge?: string;

  /**
   * Maximum total size of the local filesystem cache.
   *
   * Accepts a human-readable size string (e.g. `"10GB"`, `"500MB"`).
   * When exceeded, the oldest entries are evicted until the cache is
   * under the limit. Set to `"0"` to disable (the default).
   *
   * @defaultValue `"0"`
   */
  cacheMaxSize?: string;

  /**
   * Deprecated: The daemon is no longer used for `turbo run`.
   *
   * @defaultValue `false`
   */
  daemon?: boolean;

  /**
   * Turborepo's Environment Modes allow you to control which environment variables are available to a task at runtime.
   *
   * Documentation: https://turborepo.dev/docs/reference/configuration#envmode
   *
   * @defaultValue `"strict"`
   */
  envMode?: EnvMode;

  /**
   * When set to `true`, disables the update notification.
   *
   * @defaultValue `false`
   */
  noUpdateNotifier?: boolean;
}

export interface StartupInput {
  mode: "startup";
  globs?: Array<string>;
  withDefaults?: boolean;
}

export interface JitInput {
  mode: "jit";
  globs?: Array<string>;
  withDefaults?: boolean;
}

export interface DependencyOutputsInput {
  mode: "dependencyOutputs";
  from?: Array<string>;
  globs?: Array<string>;
}

export interface Pipeline {
  /**
   * A human-readable description of what this task does.
   *
   * This field is for documentation purposes only and does not affect
   * task execution or caching behavior.
   */
  description?: string;

  /**
   * The list of tasks that this task depends on.
   *
   * Prefixing an item in dependsOn with a ^ prefix tells turbo that this task depends
   * on the package's topological dependencies completing the task first.
   * (e.g. "A package's build tasks should only run once all of its workspace dependencies
   * have completed their own build commands.")
   *
   * Items in dependsOn without a ^ prefix express the relationships between tasks within the
   * same package (e.g. "A package's test and lint commands depend on its own build being
   * completed first.")
   *
   * Documentation: https://turborepo.dev/docs/reference/configuration#dependson
   *
   * @defaultValue `[]`
   */
  dependsOn?: Array<string>;

  /**
   * A list of environment variables that this task depends on.
   *
   * Note: If you are migrating from a turbo version 1.5 or below,
   * you may be used to prefixing your variables with a $.
   * You no longer need to use the $ prefix.
   * (e.g. $GITHUB_TOKEN → GITHUB_TOKEN)
   *
   * Documentation: https://turborepo.dev/docs/reference/configuration#env
   *
   * @defaultValue `[]`
   */
  env?: Array<EnvWildcard>;

  /**
   * An allowlist of environment variables that should be made available in this
   * task's environment, but should not contribute to the task's cache key,
   * e.g. `AWS_SECRET_KEY`.
   *
   * Documentation: https://turborepo.dev/docs/reference/configuration#passthroughenv
   *
   * @defaultValue `null`
   */
  passThroughEnv?: null | Array<EnvWildcard>;

  /**
   * The set of glob patterns indicating a task's cacheable filesystem outputs.
   *
   * Turborepo captures task logs for all tasks. This enables us to cache tasks whose runs
   * produce no artifacts other than logs (such as linters). Logs are always treated as a
   * cacheable artifact and never need to be specified.
   *
   * Documentation: https://turborepo.dev/docs/reference/configuration#outputs
   *
   * @defaultValue `[]`
   */
  outputs?: Array<string>;

  /**
   * Whether or not to cache the outputs of the task.
   *
   * Setting cache to false is useful for long-running "watch" or development mode tasks.
   *
   * Documentation: https://turborepo.dev/docs/reference/configuration#cache
   *
   * @defaultValue `true`
   */
  cache?: boolean;

  /**
   * The set of glob patterns to consider as inputs to this task.
   *
   * Changes to files covered by these globs will cause a cache miss and
   * the task will be rerun.
   *
   * If a file has been changed that is **not** included in the set of globs,
   * it will not cause a cache miss.
   *
   * If omitted or empty, all files in the package are considered as inputs.
   *
   * Documentation: https://turborepo.dev/docs/reference/configuration#inputs
   *
   * @defaultValue `[]`
   */
  inputs?: Array<string | StartupInput | JitInput | DependencyOutputsInput>;

  /**
   * Output mode for the task.
   *
   * "full": Displays all output
   *
   * "hash-only": Show only the hashes of the tasks
   *
   * "new-only": Only show output from cache misses
   *
   * "errors-only": Only show output from task failures
   *
   * "none": Hides all task output
   *
   * Documentation: https://turborepo.dev/docs/reference/run#--output-logs-option
   *
   * @defaultValue `"full"`
   */
  outputLogs?: OutputLogs;

  /**
   * Indicates whether the task exits or not. Setting `persistent` to `true` tells
   * turbo that this is a long-running task and will ensure that other tasks
   * cannot depend on it.
   *
   * Documentation: https://turborepo.dev/docs/reference/configuration#persistent
   *
   * @defaultValue `false`
   */
  persistent?: boolean;

  /**
   * Mark a task as interactive allowing it to receive input from stdin.
   * Interactive tasks must be marked with "cache": false as the input
   * they receive from stdin can change the outcome of the task.
   *
   * Documentation: https://turborepo.dev/docs/reference/configuration#interactive
   *
   * @defaultValue `false`
   */
  interactive?: boolean;

  /**
   * Label a persistent task as interruptible to allow it to be restarted by `turbo watch`.
   * `turbo watch` watches for changes to your packages and automatically
   * restarts tasks that are affected. However, if a task is persistent, it will
   * not be restarted by default. To enable restarting persistent tasks, set
   * `interruptible` to true.
   *
   * Documentation: https://turborepo.dev/docs/reference/configuration#interruptible
   *
   * @defaultValue `false`
   */
  interruptible?: boolean;

  /**
   * A list of tasks that will run alongside this task.
   *
   * Tasks in this list will not be run until completion before this task starts execution.
   *
   * Documentation: https://turborepo.dev/docs/reference/configuration#with
   *
   * @defaultValue `[]`
   */
  with?: Array<string>;
}

export interface RemoteCache {
  /**
   * Indicates if signature verification is enabled for requests to the remote cache. When
   * `true`, Turborepo will sign every uploaded artifact using the value of the environment
   * variable `TURBO_REMOTE_CACHE_SIGNATURE_KEY`. Turborepo will reject any downloaded artifacts
   * that have an invalid signature or are missing a signature.
   *
   * @defaultValue `false`
   */
  signature?: boolean;

  /**
   * Indicates if the remote cache is enabled. When `false`, Turborepo will disable
   * all remote cache operations, even if the repo has a valid token. If true, remote caching
   * is enabled, but still requires the user to login and link their repo to a remote cache.
   * Documentation: https://turborepo.dev/docs/core-concepts/remote-caching
   *
   * @defaultValue `true`
   */
  enabled?: boolean;

  /**
   * When enabled, any HTTP request will be preceded by an OPTIONS request to
   * determine if the request is supported by the endpoint.
   *
   * Documentation: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#preflighted_requests
   *
   * @defaultValue `false`
   */
  preflight?: boolean;
  /**
   * Set endpoint for API calls to the remote cache.
   * Documentation: https://turborepo.dev/docs/core-concepts/remote-caching#self-hosting
   *
   * @defaultValue `"https://vercel.com/api"`
   */
  apiUrl?: string;
  /**
   * Set endpoint for requesting tokens during `turbo login`.
   * Documentation: https://turborepo.dev/docs/core-concepts/remote-caching#self-hosting
   *
   * @defaultValue `"https://vercel.com"`
   */
  loginUrl?: string;
  /**
   * Sets a timeout for remote cache operations. Value is given in seconds and
   * only whole values are accepted. If `0` is passed, then there is no timeout
   * for any cache operations.
   *
   * @defaultValue `30`
   */
  timeout?: number;
  /**
   * Sets a timeout for remote cache uploads. Value is given in seconds and
   * only whole values are accepted. If `0` is passed, then there is no timeout
   * for any remote cache uploads.
   *
   * @defaultValue `60`
   */
  uploadTimeout?: number;

  /**
   * The ID of the Remote Cache team. Value will be passed as `teamId` in the
   * querystring for all Remote Cache HTTP calls. Must start with `team_` or it will
   * not be used.
   */
  teamId?: string;

  /**
   * The slug of the Remote Cache team. Value will be passed as `slug` in the
   * querystring for all Remote Cache HTTP calls.
   */
  teamSlug?: string;
}

export interface Permissions {
  /**
   * Lists which tags are allowed. Any tag not included will be banned
   * If omitted, all tags are permitted
   */
  allow?: Array<string>;
  /**
   * Lists which tags are banned.
   */
  deny?: Array<string>;
}

interface TagRules {
  /**
   * Rules for a tag's dependencies. Restricts which packages a tag can import
   */
  dependencies?: Permissions;
  /**
   * Rules for a tag's dependents. Restricts which packages can import this tag.
   */
  dependents?: Permissions;
}

export type BoundariesRulesMap = Record<string, TagRules>;

export interface BoundariesConfig {
  /**
   * Declares any implicit dependencies, i.e. any dependency not declared in a package.json.
   * These can include dependencies automatically injected by a framework or a testing library.
   */
  implicitDependencies?: Array<string>;
}

export interface RootBoundariesConfig extends BoundariesConfig {
  /**
   * The boundaries rules for tags. Restricts which packages
   * can import a tag and which packages a tag can import
   */
  tags?: BoundariesRulesMap;
}

export const isRootSchemaV2 = (schema: Schema): schema is RootSchema =>
  !("extends" in schema);

export const isWorkspaceSchemaV2 = (
  schema: Schema
): schema is WorkspaceSchema => !isRootSchemaV2(schema);

export type Schema = RootSchema | WorkspaceSchema;