在大型项目中使用 Biome

Biome 提供了一系列功能，有助于在大型项目中使用，例如 monorepo 或包含多个项目的 workspace。

使用多份配置文件

当使用 Biome 功能时（无论是通过 CLI 还是 LSP），工具会查找距离当前工作目录最近的配置文件。

如果 Biome 没有找到配置文件，它会 向上遍历 文件系统，直到找到一个配置文件为止。

您可以利用此功能为不同的项目/文件夹应用不同的配置。

假设我们有一个大型项目，其中包含一个前端项目和一个后端项目。

文件夹app
- 文件夹backend
  - biome.json
  - package.json
- 文件夹frontend
  - biome.json
  - 文件夹legacy-app
    package.json
  - 文件夹new-app
    package.json

此示例说明了当您在 app/backend 目录中运行 Biome 时，Biome 将使用 app/backend/biome.json 配置文件。而当您在 app/frontend/legacy-app 或 app/frontend/new-app 目录中运行时，Biome 则会使用 app/frontend/biome.json 配置文件。

Monorepo

Monorepo 是一个包含多个包的大型代码仓库。每个包都可以拥有其独立的配置。

自 v2 版本起，Biome 原生支持 monorepo，您需要按以下步骤进行配置：

在 Monorepo 根目录创建 biome.json 文件。我们将启用推荐规则并配置格式化选项：

1
{
2
  "linter": {
3
    "enabled": true,
4
    "rules": {
5
      "recommended": true
6
    }
7
  },
8
  "formatter": {
9
    "lineWidth": 120,
10
    "indentStyle": "space",
11
    "indentWidth": 6
12
  }
13
}

此文件为 根配置，用于设定项目的通用选项。嵌套配置可以选择是否继承这些选项。

为各个包创建嵌套配置文件（可根据需要创建）。这些嵌套配置文件必须包含 "root" 字段并设置为 false。此外，若要确保各包遵循根配置中的格式化规范，我们可以使用 Biome 的 新语法 "extends": "//"。该语法指示 Biome 从 根配置 继承设置，无论嵌套配置位于何处。

我们来创建两个配置文件，分别位于 packages/logger 和 packages/generate 目录下。在前者的配置中，我们将禁用 noConsole 规则，在后者的配置中，我们将禁用格式化功能，因为这些是自动生成的源代码文件：
packages/logger/biome.json
```
1
{
2
  "root": false,
3
  "extends": "//",
4
  "linter": {
5
    "rules": {
6
      "suspicious": {
7
        "noConsole": "off"
8
      }
9
    }
10
  }
11
}
```
packages/generate/biome.json
```
1
{
2
  "root": false,
3
  "extends": "//",
4
  "formatter": {
5
    "enabled": false
6
  }
7
}
```
为便于使用，我们可以省略 "root": false，因为当存在 extends 字段时，该值已被隐式设定：
packages/generate/biome.json
```
1
{
2
 "root": false,
3
  "extends": "//",
4
  "formatter": {
5
  enabled: false
6
}
```
现在，假设新增一个包位于 packages/analytics，并由另一团队维护。若该团队采用不同的编码规范，不希望继承根配置，则只需省略 "extends": "//" 并自定义格式化选项：
packages/analytics/biome.json
```
1
{
2
  "root": false,
3
  "formatter": {
4
    "lineWidth": 100
5
  }
6
}
```
配置完成后，您可以从根目录运行 biome 命令，也可以在单个包目录中运行。 Biome 将自动遵循相应的配置设置！

其他配置共享方式

如前所述，extends 字段支持将配置拆分为多个文件。借助此机制，可在多个包或不同目录间共享通用配置。虽然 "extends": "//" 语法是在嵌套配置中继承根配置的便捷方式，但在某些情况下您可能需要更灵活的配置方案。

除 "//" 外，extends 设置还接受数组形式的值。此时，数组中的每项都应指向另一个配置文件的路径。

例如，可通过如下方式配置以扩展 common.json 配置文件：

1
{
2
  "extends": ["./common.json"]
3
}

在 extends 中定义的条目相对于 biome.json 文件所在路径进行解析。各项按列表顺序处理，靠后的文件配置将覆盖先前的设置。

被 extend 的文件不能进一步 extend 其他文件。

请注意，配置文件中的路径始终相对于 biome.json/biome.jsonc 文件所在目录进行解析。使用 extends 字段时，这意味着共享配置中的路径是相对于引用它的配置文件位置解析的，而非被引用文件所在目录。

例如，假设项目包含 backend/ 和 frontend/ 两个目录，各自拥有 biome.json 文件，均扩展根目录下的 common.json 配置：

文件夹backend/
- 文件夹src/
  - …
- 文件夹test/
  - …
- biome.json
文件夹frontend/
- 文件夹src/
  - …
- 文件夹test/
  - …
- biome.json
common.json

1
{
2
  "files": {
3
    "includes": ["src/**/*.js", "test/**/*.js"]
4
  },
5
  "linter": {
6
    "includes": ["**", "!test"]
7
  }
8
}

1
{
2
  "extends": ["../common.json"]
3
}

当从 frontend/ 目录运行 Biome 时，将配置为格式化和检查 frontend/src/ 和 frontend/test/ 目录中的所有 JavaScript 文件，但仅格式化 frontend/src/ 目录中的文件。这是因为 common.json 中指定的路径相对于 frontend/ 目录解析，因为 biome.json 文件位于该目录中。
假设 backend/biome.json 与 frontend/biome.json 配置相同，则行为一致，只是路径将相对于 backend/ 目录解析。

请注意，在这种配置下，frontend/biome.json 和 backend/biome.json 均视为根配置。除非使用 --config-path CLI 选项并指向特定配置，否则无法从仓库根目录运行 Biome。

将 Biome 配置导出到 NPM 包

Biome 支持解析 node_modules/ 目录中的配置文件。因此可将 Biome 配置打包为 NPM 包，在多个项目间共享使用。

实现此目的的第一步是建立”共享” Biome 配置。假设您拥有名为 @org/shared-configs 的包，并使用 @org/shared-configs/biome 作为配置标识符。您需要在 package.json 中添加 exports 字段：

1
{
2
  "name": "@org/shared-configs",
3
  "type": "module",
4
  "exports": {
5
    "./biome": "./biome.json"
6
  }
7
}

确保 @org/shared-configs 包已在您的项目中正确安装，并按如下方式更新 biome.json 配置文件：

1
{
2
  "extends": ["@org/shared-configs/biome"]
3
}

Biome 将尝试从您的工作目录解析 @org/shared-configs/ 库。工作目录是指：

使用 CLI 时为您执行命令的目录，通常与 package.json 文件位置一致；
使用 LSP 时为项目的根目录。

有关解析算法的更多信息，请参阅 Node.js 文档。