Repo
Docs
API Reference
Configuration Options

Configuration Options (turbo.json)

You can configure the behavior of turbo by adding a turbo.json file in your monorepo's root directory.

globalDependencies

type: string[]

A list of file globs for 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) or any root level file that impacts workspace tasks (but are not represented in the traditional dependency graph (e.g. a root tsconfig.json, jest.config.js, .eslintrc, etc.)).

These must be relative paths from the location of turbo.json, and they should be valid for any machine where this configuration might be used. For instance, it is not a good idea to reference files in one user's home directory.

Example

{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    // ... omitted for brevity
  },
 
  "globalDependencies": [
    ".env", // contents will impact hashes of all tasks
    "tsconfig.json" // contents will impact hashes of all tasks
  ]
}

globalEnv

type: string[]

A list of environment variables for implicit global hash dependencies. The contents of these environment variables will be included in the global hashing algorithm and affect the hashes of all tasks.

Example

{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    // ... omitted for brevity
  },
 
  "globalEnv": ["GITHUB_TOKEN"] // value will impact the hashes of all tasks
}

globalPassThroughEnv

This goes at the root of your configuration.

type: string[]

An allowlist of environment variables that should be made available to all tasks but should not contribute to the task's cache key. Using this key opts all tasks into strict environment variable mode.

Changing this list will contribute to the global cache key, but the value of each variable will not.

Example

AWS_SECRET_KEY and GITHUB_TOKEN are available to all tasks in strict env mode.

{
  "$schema": "https://turbo.build/schema.json",
  "globalPassThroughEnv": ["AWS_SECRET_KEY", "GITHUB_TOKEN"],
  "pipeline": {
    // ...task definitions...
  }
}

globalDotEnv

type: null | string[] default: null

The ordered list of .env files to include into the global hash key's file hash.

Note: this does not load the files into the environment.

Example

{
  "$schema": "https://turbo.build/schema.json",
  "globalDotEnv": [".env.local", ".env"],
  "pipeline": {
    "build": {}
  }
}

extends

type: string[]

The extends key is only valid in Workspace Configurations. It will be ignored in the root turbo.json. Read the docs to learn more.

pipeline

An object representing the task dependency graph of your project. turbo interprets these conventions to properly schedule, execute, and cache the outputs of tasks in your project.

Each key in the pipeline object is the name of a task that can be executed by turbo run. If turbo finds a workspace with a package.json scripts object with a matching key, it will apply the pipeline task configuration to that npm script during execution. This allows you to use pipeline to set conventions across your entire Turborepo.

{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": ["^build"]
    },
    "test": {
      "outputs": ["coverage/**"],
      "dependsOn": ["build"],
      "inputs": ["src/**/*.tsx", "src/**/*.ts", "test/**/*.ts"],
      "outputMode": "full"
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

dependsOn

type: string[]

The list of tasks this task depends on.

Prefixing an item in dependsOn with a ^ tells turbo that this pipeline task depends on the workspace's topological dependencies completing the task with the ^ prefix first (e.g. "a workspace's build tasks should only run once all of its dependencies and devDependencies have completed their own build commands").

Items in dependsOn without ^ prefix, express the relationships between tasks at the workspace level (e.g. "a workspace's test and lint commands depend on build being completed first").

As of version 1.5, using $ to declare environment variables in the dependsOn config is deprecated. Use the env key instead.

Example

{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "build": {
      // "A workspace's `build` command depends on its dependencies'
      // or devDependencies' `build` command being completed first"
      "outputs": [".next/**", "!.next/cache/**", "dist/**"],
      "dependsOn": ["^build"]
    },
    "test": {
      // "A workspace's `test` command depends on its own `lint` and
      // `build` commands first being completed"
      "dependsOn": ["lint", "build"]
    },
    "deploy": {
      // "A workspace's `deploy` command, depends on its own `build`
      // and `test` commands first being completed"
      "dependsOn": ["build", "test"]
    },
    // A workspace's `lint` command has no dependencies
    "lint": {}
  }
}

dotEnv

type: null | string[] default: null

The ordered list of .env files to include into the task's file hash. These files will be included into the hash regardless of whether or not they are included in the git index.

Note: this does not load the files into the environment.

Example

{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "build": {
      "dotEnv": [".env.local", ".env"],
    }
  }
}

env

type: string[]

The list of environment variables a task depends on.

Example

{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "env": ["SOMETHING_ELSE"], // value will impact the hashes of all build tasks
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
    },
    "web#build": {
      "dependsOn": ["^build"],
      "env": ["STRIPE_SECRET_KEY"], // value will impact hash of only web's build task
      "outputs": [".next/**", "!.next/cache/**"]
    }
  },
  "globalEnv": [
    "GITHUB_TOKEN" // value will impact the hashes of all tasks
  ]
}

When Turborepo detects a common frontend framework in a workspace, it will automatically depend on environment variables that are going to be inlined in your build. For example, if the web workspace contains a Next.js project, you do not need to specify any environment variables that start with NEXT_PUBLIC_ (opens in a new tab) in the dependsOn config. Turborepo already knows that the build output will change when the value of these environment variables change, so it will depend on them automatically. See more in the docs on caching.

passThroughEnv

type: string[]

This config goes inside each task definition in the pipeline.

An allowlist of environment variables that should be made available to this task but should not contribute to the task's cache key. Using this key opts this task into strict environment variable mode.

Changing this list will contribute to the task's cache key, but the value of each variable will not.

Example

AWS_SECRET_KEY and GITHUB_TOKEN are available to the build task, but not to the lint task in strict env mode.

{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "build": {
      "passThroughEnv": ["AWS_SECRET_KEY", "GITHUB_TOKEN"]
    },
    "lint": {},
  }
}

outputs

type: string[]

The set of glob patterns of a task's cacheable filesystem outputs.

Note: turbo automatically logs stderr/stdout to .turbo/run-<task>.log. This file is always treated as a cacheable artifact and never needs to be specified.

Omitting this key or passing an empty array can be used to tell turbo that a task is a side-effect and thus doesn't emit any filesystem artifacts (e.g. like a linter), but you still want to cache its logs (and treat them like an artifact).

outputs globs must be specified as relative paths rooted at the workspace directory.

Example

{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "build": {
      // "Cache all files emitted to workspace's dist/** or .next
      // directories by a `build` task"
      "outputs": ["dist/**", ".next/**", "!.next/cache/**"],
      "dependsOn": ["^build"]
    },
    "test": {
      // "Don't cache any artifacts of `test` tasks (aside from
      // logs)"
      "dependsOn": ["build"]
    },
    "test:ci": {
      // "Cache the coverage report of a `test:ci` command"
      "outputs": ["coverage/**"],
      "dependsOn": ["build"]
    },
    "dev": {
      // Never cache anything (including logs) emitted by a
      // `dev` task
      "cache": false,
      "persistent": true
    }
  }
}

cache

type: boolean

Defaults to true. Whether or not to cache the task outputs. Setting cache to false is useful for daemon or long-running "watch" or development mode tasks you don't want to cache.

Example

{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "build": {
      "outputs": [".svelte-kit/**", "dist/**"],
      "dependsOn": ["^build"]
    },
    "test": {
      "dependsOn": ["build"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

inputs

type: string[]

Defaults to []. Tells turbo the set of files to consider when determining if a workspace has changed for a particular task. Setting this to a list of globs will cause the task to only be rerun when files matching those globs have changed. This can be helpful if you want to, for example, skip running tests unless a source file changed.

Specifying [] will cause the task to be rerun when any file in the workspace changes.

inputs globs must be specified as relative paths rooted at the workspace directory.

Example

{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    // ... omitted for brevity
 
    "test": {
      // A workspace's `test` task depends on that workspace's
      // own `build` task being completed first.
      "dependsOn": ["build"],
      "outputs": [".next/**", "!.next/cache/**"],
      // A workspace's `test` task should only be rerun when
      // either a `.tsx` or `.ts` file has changed.
      "inputs": ["src/**/*.tsx", "src/**/*.ts", "test/**/*.ts"]
    }
  }
}

Note: turbo.json is always considered an input. If you modify turbo.json, all caches are invalidated.

outputMode

type: "full" | "hash-only" | "new-only" | "errors-only" | "none"

Set type of output logging. Can be overriden by the --output-logs CLI option.

optiondescription
fullDisplays all output (default)
hash-onlyShow only the hashes of the tasks
new-onlyOnly show output from cache misses
errors-onlyOnly show output from task failures
noneHides all task output

Example

{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".svelte-kit/**", "dist/**"],
      "outputMode": "new-only"
    },
    "test": {
      "dependsOn": ["build"]
    }
  }
}

persistent

type: boolean

Label a task as persistent if it is a long-running process, such as a dev server or --watch mode. Turbo will prevent other tasks from depending on persistent tasks. Without setting this config, if any other task depends on dev, it will never run, because dev never exits. With this option, turbo can warn you about an invalid configuration.

Example

{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "dev": {
      "persistent": true
    }
  }
}
Configuring WorkspacesCLI Usage