Turbo

web开发技术

Demo

npx create-turbo@latest

Install

pn add turbo -D --ignore-workspace-root-check

核心配置

workspaces

# pnpm-workspace.yaml
packages:
 - "packages/*"
 - "apps/*"

.gitignore

# ...
.turbo

pipeline

// turbo.json
{
    "$schema": "https://turborepo.org/schema.json",
    "pipeline": {
        "build": {
            "build": {
                // "^" 表示执行 turbo run build 时
                // 每个有 build 脚本的 pkg 处理拓扑依赖（upstream mono deps）
                "dependsOn": ["^build"],
                // 路径相对于 packages/**/package.json
                "outputs": [".next/**"]
            }
        },
        "test": {
            // 执行 turbo run test 会先执行依赖的 turbo run build
            "dependsOn": ["build"],
            "outputs": [],
            // 只有下列文件发生变更才需要重新执行
            "inputs": [
                "src/**/*.tsx",
                "src/**/*.ts",
                "test/**/*.tsx",
                "test/**/*.ts"
            ]
        },
        "lint": {
            // 随时可以执行
            outputs: []
        },
        "deploy": {
            "dependsOn": [
                "build",
                "test",
                "lint"
            ],
            "outputs": []
        }
    }
}

若某个包的 package.json 里没有 pipeline task 对应的 script，那个包会被忽略执行这个 task。

turbo 只能执行 pipeline 里指定了的任务。

//#<task> 用来配置根目录下的 package.json 也需要执行的任务

{
  "$schema": "https://turborepo.org/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": ["^build"]
    },
    // "turbo run test" 会触发工作区 package.json 的 test 脚本
    "test": {
      "dependsOn": ["^build"],
      "outputs": [],
    },
    // "turbo run test" 会触发根目录 package.json 的 test 脚本
    "//#test": {
      "dependsOn": [],
      "outputs": []
    },
    // "turbo run format" 会触发根目录 package.json 的 format 脚本
    // 由于 pipeline 没有 "format" 任务，不会触发工作区的任何脚本
    "//#format": {
      "dependsOn": [],
      "outputs": ["dist/**/*"],
      "inputs": ["version.txt"]
    },
  }
}

复杂依赖

使用 <package>#<task> 可以单独配置某个包的某个任务，或指定某个包的某个任务为依赖：

{
  "$schema": "https://turborepo.org/schema.json",
  "pipeline": {
    // Standard configuration
    "build": {
      "dependsOn": ["^build"]
    },
    "test": {
      "dependsOn": ["^build"],
      "outputs": [],
    },
    "deploy": {
      "dependsOn": ["test", "build"],
      "outputs": []
    },
    // Explicit package-task to package-task dependency
    "frontend#deploy": {
      "dependsOn": ["ui#test", "backend#deploy", "backend#health-check"],
      "outputs": []
    },
  }
}

package-tasks 不会继承缓存配置，需要重新声明 outputs

CLI

--filter

--filter= 参数使命令过滤不符合条件的 pkgs

• 直接声明包名

turbo run build --filter=my-pkg
turbo run build --filter=@foo/bar
# 以 'admin-' 开头的包
turbo run build --filter=admin-*

• // 指定为根目录

turbo run format --filter=//

• ... 前缀指定具有某个依赖

# 所有依赖了 my-lib 的 package.json 会触发 test 脚本，包括 my-lib 自己
turbo run test --filter=...my-lib
# 同上，但不包括 my-lib 自己
turbo run test --filter=...^my-lib

• ... 后缀指定某个包的依赖

# build my-app 及其依赖
turbo run build --filter=my-app...
# build my-app 的依赖，不包括 my-app 自己
turbo run build --filter=my-app^...

• 指定某个目录下的包
  需要指定到包的目录，或使用 glob 表达式；和 ... 或者包名组合使用的时候用 {} 包裹目录。

turbo run build --filter=./apps/*

# build 'libs' 下的所有包，以及依赖它们的包
turbo run build --filter=...{./libs/*}

turbo run test --filter=@foo/*{./packages/*}

• 指定变更过的包
  用 [] 指定 git commit 的 diff，turbo 会选择所有在 commit diff 里变更的包；同样可以结合 ... 使用

# Test everything that changed in the last commit
turbo run test --filter=[HEAD^1]
# 依赖 'my-feature' 分支的改动的所有包
turbo run build --filter=...[origin/my-feature]
# 上一次 commit 后有变更的 @foo/bar 及其依赖
turbo run build --filter=@foo/bar...[HEAD^1]
# 在 @scope 域且在 'packages' 目录下
# 且在上次 commit 后发生变更的包
turbo run test --filter=@scope/*{./packages/*}[HEAD^1]
# 'main' 分支和 'my-featur' 分支之间发生变更的包
turbo run test --filter=[main...my-feature]

可以配合 --ignore cli 参数

--ignore

turbo run build --ignore="apps/**/*"
turbo run build --ignore="packges/**/*" --ignore="\!/packages/not-this-one/**/*"

正向规则（例如 foo/*）添加文件，负向规则（例如 !foo）减少文件；因此只使用负向规则 [!foo] 并不会匹配任何内容，应该使用 ['*', '!foo']

glob 规则

• *：匹配任意个任意字符，除了 /
• ?：匹配单个任意字符，除了 /
• **：匹配任意个任意字符，包括 /
• {}：支持由逗号分隔的多个“或”表达式
• !：负向规则开头

缓存

turbo run 默认认为通过 scripts 输出到每个 pipeline 的 outputs 目录的内容是可缓存的；并会在包目录 .turbo/run-<command>.log 下生成可缓存的运行日志，通过对运行日志的缓存，可以告诉 turbo 使用缓存。

使用 pipeline.<task>.outputs globs 来说明需要缓存的产物目录。

{
    "$schema": "https://turborepo.org/schema.json",
    "pipeline": {
        "build": {
            "outputs": ["dist/**", ".next/**"],
            "dependsOn": ["^build"]
        },
        "test": {
            "outputs": [], // 只会缓存 log
            "dependsOn": ["build"]
        }
    }
}

outputs 的产物和对应任务的日志都会被缓存在 ./node_modules/.cache/turbo 目录下。

删除 outputs 指定目录下的真实产物不影响 ./node_modules/.cache/turbo 缓存。

关闭缓存

使用 cli 参数 --no-cache 可以关闭该命令的缓存：

trubo run dev --parallel --no-cache

设置 pipeline.<task>.cache 为 false 可以关闭某个 script 的缓存：

{
    "$schema": "https://turborepo.org/schema.json",
    "pipeline": {
        "dev": {
            "cache": false
        }
    }
}

判断缓存有效性

使用 pipeline.<task>.inputs 告知 turbo 是否缓存是否过期的判断文件：

{
    "$schema": "https://turborepo.org/schema.json",
    "pipeline": {
        "test": {
            "outpus": [],
            "dependsOn": ["build"],
            "inputs": [
                "src/**/*.tsx",
                "src/**/*.ts",
                "test/**/*.ts"
            ]
        }
    }
}

特殊的是 turbo.json 文件的变更会使所有缓存失效。

在开发环境发生变更后，缓存通常会失效。turbo 允许通过环境变量和 contenthash 的结合来控制缓存：

• 使用 $ 前缀的环境变量可以添加到 pipeline.<task>.dependsOn 数组中，从而影响某个任务的缓存 hash
• 全局的任务依赖数组 globalDependencies 中使用 $ 前缀的环境变量则会影响所有任务的缓存 hash
• 任何变量名中包含 THASH 的环境变量，例如：STRIPE_PUBLIC_THASH_SECRET_KEY 会影响所有任务的缓存 hash

对于一些构建框架（例如 Next/Nuxt/CRA/Vite/Vue）的一些 CI 环境变量，turbo 已经自动集成了