Skip to content

Commit

Permalink
docs: document new ui configuration options (#7803)
Browse files Browse the repository at this point in the history
### Description

Document new options for the experimental UI + interactive tasks.

### Testing Instructions

👀 


Closes TURBO-2680
  • Loading branch information
chris-olszewski committed Mar 21, 2024
1 parent 2a7b6c6 commit ada6815
Show file tree
Hide file tree
Showing 2 changed files with 34 additions and 14 deletions.
47 changes: 33 additions & 14 deletions docs/pages/repo/docs/reference/configuration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ 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'
import Link from "next/link";

# Configuration Options (`turbo.json`)

Expand All @@ -19,8 +19,10 @@ A list of file globs for global hash dependencies. The contents of these files w
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.
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**
Expand Down Expand Up @@ -113,6 +115,13 @@ Note: this does _not_ load the files into the environment.
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].

## `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.
Expand Down Expand Up @@ -151,8 +160,9 @@ Prefixing an item in `dependsOn` with a `^` tells `turbo` that this pipeline tas
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>
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**
Expand Down Expand Up @@ -199,7 +209,7 @@ Note: this does _not_ load the files into the environment.
"$schema": "https://turbo.build/schema.json",
"pipeline": {
"build": {
"dotEnv": [".env.local", ".env"],
"dotEnv": [".env.local", ".env"]
}
}
}
Expand Down Expand Up @@ -271,7 +281,7 @@ in `strict` [env mode][r-cli-env-mode].
"build": {
"passThroughEnv": ["AWS_SECRET_KEY", "GITHUB_TOKEN"]
},
"lint": {},
"lint": {}
}
}
```
Expand All @@ -293,7 +303,8 @@ and thus doesn't emit any filesystem artifacts (e.g. like a linter), but you sti
logs (and treat them like an artifact).

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

**Example**
Expand Down Expand Up @@ -365,11 +376,10 @@ changed. This can be helpful if you want to, for example, skip running tests unl
explicitly depend on a `.gitignore`d file.

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

Expand Down Expand Up @@ -398,7 +408,7 @@ when you want to add or remove additional inputs from the default set.
"pipeline": {
"check-types": {
// Consider all default inputs except the README.md
"inputs": ["$TURBO_DEFAULT$", "!README.md"],
"inputs": ["$TURBO_DEFAULT$", "!README.md"]
}
}
}
Expand Down Expand Up @@ -452,6 +462,15 @@ option, `turbo` can warn you about an invalid configuration.
}
```

### `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:
Expand Down
1 change: 1 addition & 0 deletions docs/pages/repo/docs/reference/system-variables.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ By setting certain environment variables, you can change Turborepo's behavior. T
| `TURBO_BINARY_PATH` | Manually set the path to the `turbo` binary. By default, `turbo` will automatically discover the binary so you should only use this in extremely rare circumstances. |
| `TURBO_CACHE_DIR` | Sets the cache directory, similarly to calling `--cache-dir`-argument |
| `TURBO_CI_VENDOR_ENV_KEY` | Set a prefix for environment variables that you want **excluded** from [Framework Inference](/repo/docs/core-concepts/caching/environment-variable-inputs#framework-inference). |
| `TURBO_EXPERIMENTAL_UI` | Enable experimental UI for `turbo`. Allowed values are `true` and `false`. |
| `TURBO_FORCE` | Always force all tasks in your pipelines to run in full, opting out of all caching. |
| `TURBO_LOG_ORDER` | Set the [log order](https://turbo.build/repo/docs/reference/command-line-reference/run#--log-order) for your pipeline's logs. Allowed values are `grouped` and `default`. |
| `TURBO_LOGIN` | Set the URL used to log in to [Remote Cache](/repo/docs/core-concepts/remote-caching). |
Expand Down

0 comments on commit ada6815

Please sign in to comment.