---
title: Configuration
description: Learn how to configure Turborepo through `turbo.json`.
---

import { Callout } from "../../../../components/Callout";
import OutputModeTable from "../../../../components/output-mode-table.mdx";
import Link from 'next/link'

# 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.)).

<Callout type="info">
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.
</Callout>

**Example**

```jsonc
{
  "$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**

```jsonc
{
  "$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][r-cli-env-mode].

```jsonc
{
  "$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**

```jsonc
{
  "$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][1].

## `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.

```jsonc
{
  "$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").

<Callout type="info">
  As of version 1.5, using `$` to declare environment variables in the `dependsOn` config is
  deprecated. <Link href="#env">Use the `env` key instead.</Link>
</Callout>

**Example**

```jsonc
{
  "$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**

```jsonc
{
  "$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**

```jsonc
{
  "$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
  ]
}
```

<Callout type="info">
  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_`](https://nextjs.org/docs/basic-features/environment-variables#exposing-environment-variables-to-the-browser)
  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](/repo/docs/core-concepts/caching#automatic-environment-variable-inclusion).
</Callout>

### `passThroughEnv`

`type: string[]`

This config goes inside each task definition in the [`pipeline`][r-config-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][r-cli-env-mode].

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

[r-config-pipeline]: #pipeline
[r-cli-env-mode]: /repo/docs/reference/command-line-reference/run#--env-mode

### `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).

<Callout type="info">
  `outputs` globs must be specified as relative paths rooted at the workspace directory.
</Callout>

**Example**

```jsonc
{
  "$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`](#outputs). Setting `cache` to false is useful for daemon or long-running "watch" or development mode tasks you don't want to cache.

**Example**

```jsonc
{
  "$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.

The default is `[]` to run the task when any file in the package changes.

<Callout type="info">
  `inputs` globs must be specified as relative paths rooted at the package's directory.
</Callout>

**Example**

```jsonc
{
  "$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"]
    }
  }
}
```

<Callout type="info">
  Note: `turbo.json` is *always* considered an input. If you modify
  `turbo.json`, all caches are invalidated.
</Callout>

### `outputMode`

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

Set type of output logging. Can be overriden by the [`--output-logs`](/repo/docs/reference/command-line-reference/run#--output-logs) CLI option.

<OutputModeTable />

**Example**

```jsonc
{
  "$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**

```jsonc
{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "dev": {
      "persistent": true
    }
  }
}
```

[1]: /repo/docs/core-concepts/monorepos/configuring-workspaces
