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.
experimentalUI
type: bool
Enable use of the new UI for turbo
.
Can be overriden by the TURBO_EXPERIMENTAL_UI
environment variable.
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[]
Tells turbo
the set of files to consider when determining if a package has changed for a particular task.
Setting this to a list of globs will cause the task to only be run 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, or
explicitly depend on a .gitignore
d file.
Good to know: - The default for inputs
is []
to run the task when any file
in the package changes. - inputs
globs must be specified as relative paths
rooted at the package's directory. - turbo.json
is always considered an
input. If you modify turbo.json
, all caches are invalidated.
Example
{
"$schema": "https://turbo.build/schema.json",
"pipeline": {
"test": {
// A package's `test` task should only be ran when
// either a `.tsx` or `.ts` file has changed.
"inputs": ["src/**/*.tsx", "src/**/*.ts", "test/**/*.ts"]
}
}
}
Because specifying an inputs
key immediately opts out of the default behavior, you may specify
the special string $TURBO_DEFAULT$
within an inputs array to start with the default inputs. This is useful
when you want to add or remove additional inputs from the default set.
Example with $TURBO_DEFAULT$
:
{
"$schema": "https://turbo.build/schema.json",
"pipeline": {
"check-types": {
// Consider all default inputs except the README.md
"inputs": ["$TURBO_DEFAULT$", "!README.md"]
}
}
}
outputMode
type: "full" | "hash-only" | "new-only" | "errors-only" | "none"
Set type of output logging. Can be overriden by the --output-logs
CLI option.
option | description |
---|---|
full | Displays all output (default) |
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 |
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
}
}
}
interactive
type: 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.
turbo
will only run interactive tasks if hooked up to a TTY and the experimental UI is in use.
Glob specification for paths
Turborepo's glob implementation allows you to specfically define the files you want turbo
to interact with. The most useful patterns you'll need are in the table below:
Pattern | Description |
---|---|
* | Match all files in the directory |
** | Recursively match all files and sub-directories |
some-dir/ | Match the some-dir directory but not its contents |
some-dir* | Match files and directories that start with some-dir |
*.js | Matches all .js files in the directory |
*.{js,ts,tsx,jsx} | Matches all files that end with the provided extensions in the directory |
*.{js?x} | Matches all files with the js and jsx extensions in the directory |
! | Negate the whole glob (automatically applies /** to the end of the defined glob) |
Here are a few examples of how to use these patterns:
Pattern | Description |
---|---|
dist/** | Match all files in the dist directory and all sub-directories |
dist/some-dir/** | Match all files in the dist/some-dir directory and all sub-directories in the current directory |
dist/ | Match the dist directory but not its contents |
dist | Match the dist directory but not its contents |
!dist | Ignore the dist directory and all of its contents |
dist* | Match files and directories that start with dist |
dist/*.js | Match all .js files in the dist directory |
!dist/*.js | Ignore all .js files in the dist directory |
dist/**/*.js | Recursively match all .js files in the dist directory and its sub-directories |
../scripts/** | Up one directory, match all files and sub-directories in the scripts directory |