diff --git a/docs/pages/docs/features/caching.mdx b/docs/pages/docs/features/caching.mdx index a039f3968248c..bba7936631ace 100644 --- a/docs/pages/docs/features/caching.mdx +++ b/docs/pages/docs/features/caching.mdx @@ -14,20 +14,18 @@ By default, [`turbo run`](../reference/command-line-reference#turbo-run-task1-ta Using [`pipeline`](../reference/configuration#pipeline), you can configure cache conventions across your Turborepo. -To override the default cache folder behavior, pass an array of globs to a [`pipeline..outputs`](../reference/configuration#outputs) array. Any file that satisfies the glob patterns for a task will be treated as artifact. +To override the default cache output behavior, pass an array of globs to a [`pipeline..outputs`](../reference/configuration#outputs) array. Any file that satisfies the glob patterns for a task will be treated as artifact. ```json { - "turbo": { - "pipeline": { - "build": { - "outputs": ["dist/**", ".next/**"], - "dependsOn": ["^build"] - }, - "test": { - "outputs": [], // leave empty to only cache logs - "dependsOn": ["build"] - } + "pipeline": { + "build": { + "outputs": ["dist/**", ".next/**"], + "dependsOn": ["^build"] + }, + "test": { + "outputs": [], // leave empty to only cache logs + "dependsOn": ["build"] } } } @@ -65,11 +63,9 @@ You can also always disable caching on a specific task by setting `cache` to `fa ```json { - "turbo": { - "pipeline": { - "dev": { - "cache": false - } + "pipeline": { + "dev": { + "cache": false } } } @@ -88,7 +84,7 @@ Luckily, you can control `turbo`'s cache fingerprinting (a.k.a. hashing) behavio ```json { - "turbo": { + "pipeline": { "build": { "dependsOn": { @@ -125,7 +121,7 @@ Luckily, you can control `turbo`'s cache fingerprinting (a.k.a. hashing) behavio "tsconfig.json" // file contents will impact the hashes of all tasks, ".env.*" // glob file contents will impact the hashes of all tasks, ], - } + } ``` diff --git a/docs/pages/docs/features/pipelines.mdx b/docs/pages/docs/features/pipelines.mdx index 336e67acab925..90911792d3d48 100644 --- a/docs/pages/docs/features/pipelines.mdx +++ b/docs/pages/docs/features/pipelines.mdx @@ -26,23 +26,21 @@ To define your project's task dependency graph, use the [`pipeline`](../referenc Each key in the [`pipeline`](../reference/configuration#pipeline) object is the name of a task that can be executed by [`turbo run`](../reference/command-line-reference#turbo-run-task1-task2-1). You can specify its dependencies with the [`dependsOn`](../reference/configuration#dependson) key beneath it as well as some other options related to [caching](./caching). -An example Pipeline configuration: +An example Pipeline configuration in `turbo.json`: ```json { - "turbo": { - "pipeline": { - "build": { - "dependsOn": ["^build"] - }, - "test": { - "dependsOn": ["build"] - }, - "deploy": { - "dependsOn": ["build", "test", "lint"] - }, - "lint": {} - } + "pipeline": { + "build": { + "dependsOn": ["^build"] + }, + "test": { + "dependsOn": ["build"] + }, + "deploy": { + "dependsOn": ["build", "test", "lint"] + }, + "lint": {} } } ``` @@ -68,30 +66,28 @@ What you are declaring here in the `pipeline` object of the `turbo` configuratio ```json { - "turbo": { - "pipeline": { - "build": { - // A package's `build` task depends on that package's - // topological dependencies' and devDependencies' - // `build` tasks being completed - // (that's what the `^` symbol signifies). - "dependsOn": ["^build"] - }, - "test": { - // A package's `test` task depends on the `build` - // task of the same package being completed. - "dependsOn": ["build"] - }, - "deploy": { - // A package's `deploy` task depends on the `build`, - // `test`, and `lint` tasks of the same package - // being completed. - "dependsOn": ["build", "test", "lint"] - }, - // A package's `lint` task has no dependencies and - // can be run whenever. - "lint": {} - } + "pipeline": { + "build": { + // A package's `build` task depends on that package's + // topological dependencies' and devDependencies' + // `build` tasks being completed + // (that's what the `^` symbol signifies). + "dependsOn": ["^build"] + }, + "test": { + // A package's `test` task depends on the `build` + // task of the same package being completed. + "dependsOn": ["build"] + }, + "deploy": { + // A package's `deploy` task depends on the `build`, + // `test`, and `lint` tasks of the same package + // being completed. + "dependsOn": ["build", "test", "lint"] + }, + // A package's `lint` task has no dependencies and + // can be run whenever. + "lint": {} } } ``` @@ -104,15 +100,13 @@ A common pattern in many TypeScript monorepos is to declare that a package's `bu ```json { - "turbo": { - "pipeline": { - "build": { - // "A package's `build` command depends on its dependencies' - // and devDependencies' `build` commands being completed first" - "dependsOn": ["^build"] - } - // ... omitted for brevity + "pipeline": { + "build": { + // "A package's `build` command depends on its dependencies' + // and devDependencies' `build` commands being completed first" + "dependsOn": ["^build"] } + // ... omitted for brevity } } ``` @@ -123,8 +117,7 @@ An empty dependency list (`dependsOn` is either undefined or `[]`) means that a ```json { - "turbo": { - "pipeline": { + "pipeline": { // ... omitted for brevity // A package's `lint` command has no dependencies and can be run at @@ -152,7 +145,7 @@ For these cases, you can express these relationships in your `pipeline` configur ```json { - "turbo": { + "pipeline": { "build": { "dependsOn": ["^build"] @@ -167,7 +160,7 @@ For these cases, you can express these relationships in your `pipeline` configur "dependsOn": ["ui#test", "backend#deploy", "backend#health-check"] } } - } + } ``` diff --git a/docs/pages/docs/features/scopes.mdx b/docs/pages/docs/features/scopes.mdx index 615eb06e4a8ac..5c79cb78927a0 100644 --- a/docs/pages/docs/features/scopes.mdx +++ b/docs/pages/docs/features/scopes.mdx @@ -39,4 +39,5 @@ turbo run build --scope=*build-tools* --no-deps --include-dependencies Turborepo's Scoped Tasks API design and docs were/are inspired [Microsoft's Lage project](https://microsoft.github.io/lage/guide/scopes.html#scoped-builds-with-all-its-dependents) `--scope` flag which was inspired by [Lerna's](https://github.com/lerna/lerna/tree/main/commands/run#readme). We are working toward a new, more expressive task filtering/scoping syntax. [Read the RFC here.](https://github.com/vercel/turborepo/discussions/105) + diff --git a/docs/pages/docs/guides/migrate-from-lerna.mdx b/docs/pages/docs/guides/migrate-from-lerna.mdx index 99902e34971ec..6028c608b7818 100644 --- a/docs/pages/docs/guides/migrate-from-lerna.mdx +++ b/docs/pages/docs/guides/migrate-from-lerna.mdx @@ -94,20 +94,25 @@ Alter `package.json` to use `turbo` for task running, but keep `lerna` for versi "devDependencies": { "lerna": "^3.19.0", + "turbo": "*" - }, -+ "turbo": { -+ "pipeline": { -+ "build": { -+ "dependsOn": ["^build"], -+ "outputs": ["dist/**"] -+ }, -+ "test": { -+ "outputs": [] -+ }, -+ "dev": { -+ "cache": false -+ } -+ } + } +} +``` + +Create a `turbo.json` file in the root of your project. + +```json +{ + "pipeline": { + "build": { + "dependsOn": ["^build"], + "outputs": ["dist/**"] + }, + "test": { + "outputs": [] + }, + "dev": { + "cache": false + } } } ``` diff --git a/docs/pages/docs/reference/command-line-reference.mdx b/docs/pages/docs/reference/command-line-reference.mdx index c3ba473e19842..8997e7e8ac623 100644 --- a/docs/pages/docs/reference/command-line-reference.mdx +++ b/docs/pages/docs/reference/command-line-reference.mdx @@ -96,13 +96,10 @@ turbo run build test lint --graph=my-graph.png turbo run build test lint --graph=my-graph.html ``` - + **Known Bug**: All possible pipeline task nodes will be added to the graph at the moment, even if that pipeline task does not actually exist in a - given package. This has no impact on execution, it means that: - -- the terminal output may overstate the number of packages in which a task is running. -- your dot viz graph may contain additional nodes that represents tasks that do not exist. + given package. This has no impact on execution, it means that 1) the terminal output may overstate the number of packages in which a task is running and 2) your dot viz graph may contain additional nodes that represents tasks that do not exist. #### `--force` @@ -171,22 +168,20 @@ turbo run dev --parallel --no-cache Default false. Restricts execution to only include specified tasks. This is very similar to how how `lerna` or `pnpm` run tasks by default. -Given this pipeline: +Given this pipeline in `turbo.json`: ```json { - "turbo": { - "pipeline": { - "build": { - "dependsOn": [ - "^build" - ] - }, - "test": { - "dependsOn": [ - "^build" - ] - } + "pipeline": { + "build": { + "dependsOn": [ + "^build" + ] + }, + "test": { + "dependsOn": [ + "^build" + ] } } } @@ -211,7 +206,7 @@ turbo run dev --parallel --no-cache `type: string[]` -Specify/filter package(s)/apps to act as entry points for execution. Globs against package.json `name` field (and not the file system.) +Specify/filter package(s)/apps to act as entry points for execution. Globs against `package.json` `name` field (and not the file system.) ```sh turbo run lint --scope="@example/**" @@ -236,7 +231,7 @@ Filter execution based on which packages have changed since a merge-base. turbo run build --since=origin/main ``` - + **Important**: This uses the `git diff ${target_branch}...` mechanism to identify which packages have changed. There is an assumption that all the input files for a package exist inside their respective package/app folders. @@ -271,7 +266,7 @@ You can also set the value of the current team by setting an environment variabl To view CPU trace, outputs the trace to the given file, use `go tool trace [file]`. - + **Important**: The trace viewer doesn't work under Windows Subsystem for Linux. @@ -295,9 +290,9 @@ turbo run build --heap="" To view CPU profile, outputs the profile to the given file, drop the file into [speedscope](https://speedscope.app). - + **Important**: The CPU profiler doesn't work under - Windows subsystem for Linux. The profiler has to be built + Windows Subsystem for Linux. The profiler has to be built for native Windows and run using the command prompt instead.