Configuration Options (turbo.json
)
You can configure the behavior of turbo
by adding a turbo.json
file in your monorepo's root (i.e. the same one you specify your workspaces
key is set for Yarn and npm users).
globalDependencies
type: string[]
A list of globs and environment variables for implicit global hash dependencies. Environment variables should be prefixed with $
(e.g. $GITHUB_TOKEN
). Any other entry without this prefix, will be considered filesystem glob. 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), environment variables, or any root level file that impacts package tasks (but are not represented in the traditional dependency graph (e.g. a root tsconfig.json
, jest.config.js
, .eslintrc
, etc.)).
Example
{
"$schema": "https://turborepo.org/schema.json",
"pipeline": {
// ... omitted for brevity
},
"globalDependencies": [
".env", // contents will impact hashes of all tasks
"tsconfig.json", // contents will impact hashes of all tasks
"$GITHUB_TOKEN"// value will impact the hashes of all tasks
]
}
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 package 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://turborepo.org/schema.json",
"pipeline": {
"build": {
"dependsOn": ["^build"]
},
"test": {
"outputs": ["coverage/**"],
"dependsOn": ["build"],
"inputs": ["src/**/*.tsx", "src/**/*.ts", "test/**/*.ts"],
"outputMode": "full"
},
"dev": {
"cache": false
}
}
}
dependsOn
type: string[]
The list of tasks and environment variables that this task depends on.
Prefixing an item in dependsOn
with a ^
tells turbo
that this pipeline task depends on the package's topological dependencies completing the task with the ^
prefix first (e.g. "a package'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 package level (e.g. "a package's test
and lint
commands depend on build
being completed first").
Prefixing an item in dependsOn
with a $
tells turbo
that this pipeline task depends the value of that environment variable.
Example: Basics
{
"$schema": "https://turborepo.org/schema.json",
"pipeline": {
"build": {
// "A package's `build` command depends on its dependencies'
// or devDependencies' `build` command being completed first"
"dependsOn": ["^build"]
},
"test": {
// "A package's `test` command depends on its own `lint` and
// `build` commands first being completed"
"dependsOn": ["lint", "build"]
},
"deploy": {
// "A package's `deploy` command, depends on its own `build`
// and `test` commands first being completed"
"dependsOn": ["build", "test"]
},
// A package's `lint` command has no dependencies
"lint": {}
}
}
Example: Environment Variables and Tasks
{
"$schema": "https://turborepo.org/schema.json",
"pipeline": {
"build": {
"dependsOn": [
"^build",
"$SOMETHING_ELSE" // value will impact the hashes of all build tasks
],
"outputs": ["dist/**", ".next/**"]
},
"web#build": {
"dependsOn": [
"^build",
"$STRIPE_SECRET_KEY", // value will impact hash of only web's build task
"$NEXT_PUBLIC_STRIPE_PUBLIC_KEY"
],
"outputs": [".next/**"]
}
},
"globalDependencies": [
"$GITHUB_TOKEN"// value will impact the hashes of all tasks
]
}
outputs
type: string[]
Defaults to ["dist/**", "build/**"]
. 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.
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).
Example
{
"$schema": "https://turborepo.org/schema.json",
"pipeline": {
"build": {
// "Cache all files emitted to package's dist/** or .next
// directories by a `build` task"
"outputs": ["dist/**", ".next/**"],
"dependsOn": ["^build"]
},
"test": {
// "Don't cache any artifacts of `test` tasks (aside from
// logs)"
"outputs": [],
"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
}
}
}
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 that you don't want to cache.
Example
{
"$schema": "https://turborepo.org/schema.json",
"pipeline": {
"build": {
"dependsOn": ["^build"]
},
"test": {
"outputs": [],
"dependsOn": ["build"]
},
"dev": {
"cache": false
}
}
}
inputs
type: string[]
Defaults to []
. 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 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 changes.
Example
{
"$schema": "https://turborepo.org/schema.json",
"pipeline": {
// ... omitted for brevity
"test": {
// A package's `test` task depends on that package's
// own `build` task being completed first.
"dependsOn": ["build"],
"outputs": [""],
// A package's `test` task should only be rerun when
// either a `.tsx` or `.ts` file has changed.
"inputs": ["src/**/*.tsx", "src/**/*.ts", "test/**/*.ts"]
}
}
}
outputMode
type: string
Defaults to full
. The style of output for the task. Use "full" to display the entire output of the task. Use "hash-only" to show only the computed task hashes. Use "new-only" to show the full output of cache misses and the computed hashes for cache hits. Use "none" to hide task output.
Example
{
"$schema": "https://turborepo.org/schema.json",
"pipeline": {
"build": {
"dependsOn": ["^build"],
"outputMode": "new-only"
},
"test": {
"outputs": [],
"dependsOn": ["build"],
},
}
}