在大型项目中使用 Biome

Biome 可以提供一些工具来帮助你在大型项目中正确使用它，例如 monorepo 或包含多个项目的工作区。

¥Biome can provide some tools that can help you to use it properly in big projects, such as monorepo or workspaces that contain multiple projects.

使用多个配置文件

¥Use multiple configuration files

当你使用 Biome 的功能时 - 使用 CLI 或 LSP - 该工具使用当前工作目录查找最近的配置文件。

¥When you use Biome’s features - either with the CLI or LSP - the tool looks for the nearest configuration file using the current working directory.

如果 Biome 找不到配置文件，它会向上遍历文件系统的目录，直到找到为止。

¥If Biome doesn’t find the configuration file there, it starts traversing upwards the directories of the file system, until it finds one.

你可以利用此功能根据项目/文件夹应用不同的设置。

¥You can leverage this feature to apply different settings based on the project/folder.

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

¥Let’s suppose we have a project that contains a backend app and a frontend app.

• Directory

  app

  • Directory

    backend

    • biome.json

    • package.json

  • Directory

    frontend

    • biome.json

    • Directory

      legacy-app

      • package.json
    • Directory

      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。

¥This means that when you run Biome inside app/backend, Biome will use the configuration file app/backend/biome.json. And when you run from app/frontend/legacy-app or app/frontend/new-app, Biome will use the configuration file app/frontend/biome.json.

Monorepo

单体仓库（Monorepos）是一种特殊的仓库，它将多个包存储和维护在一个大型仓库中。每个包都可以包含自己的配置。

¥Monorepos are particular repositories where multiple packages are stored and maintained in one big repository. Each package can contain its own configuration.

自 v2 版本起，Biome 开箱即用地支持单体仓库，你需要按以下方式设置项目。

¥Since v2, Biome supports monorepos out of the box, and you’ll need to set up the project in the following way.

1. 在 monorepo 的根目录创建 biome.json 文件。我们将使用推荐规则，并自定义格式化选项：

   ¥Create a biome.json file at the root of the monorepo. We will use the recommended rules, and customise the formatter options:

   biome.json

   {
       "linter": {
           "enabled": true,
           "rules": {
               "recommended": true
           }
       },
       "formatter": {
           "lineWidth": 120,
           "indentStyle": "space",
           "indentWidth": 6
       }
   }

   此文件称为根配置，它设置项目内的基本选项。嵌套配置可以自行决定是否遵循这些选项。让我们看看它是如何工作的。

   ¥This file is called the root configuration and it sets the base options inside the project. However, nested configurations can decide to adhere to these options or not. Let’s see how.

2. 创建嵌套配置文件，每个需要的包中各一个。这些嵌套配置文件必须将字段 "root" 设置为 false。此外，我们希望这些包遵循根配置中设置的格式标准。为此，我们将使用 Biome v2 中新增的微语法 "extends": "//"。此语法指示 Biome 从根配置继承，而不管嵌套配置位于何处。

   ¥Create nested configuration files, one in each package where it is needed. These nested configuration files must have the field "root" set to false. Also, we want these packages to follow the formatting standards set up in the root configuration. In order to so, we will use a new microsyntax available in Biome v2, which is "extends": "//". This syntax tells Biome to extend from the root configuration, regardless of where the nested configuration is.

   让我们创建两个配置文件，一个位于 packages/logger 中，另一个位于 packages/generate 中。在前一个示例中，我们将禁用 noConsole；在 packages/generate 示例中，我们将禁用格式化程序，因为这些文件是由代码生成的：

   ¥Let’s create two configuration files, one inside packages/logger and one inside packages/generate. In the former we will disable noConsole, and in packages/generate we will disable the formatter because those are files that are code-generated:

   packages/logger/biome.json

   {
       "root": false,
       "extends": "//",
       "linter": {
           "rules": {
               "suspicious": {
                   "noConsole": "off"
               }
           }
       }
   }

   packages/generate/biome.json

   {
       "root": false,
       "extends": "//",
       "formatter": {
           "enabled": false
       }
   }

   为了方便起见，在使用微语法 extends: "//" 时，可以省略 "root": false，因为 extends: "//" 已经表明该配置不是根配置：

   ¥For convenience, when you use the microsyntax extends: "//", you can omit "root": false, because it is already implied that this configuration isn’t a root configuration:

   packages/generate/biome.json

   {
      "root": false,
       "extends": "//",
       "formatter": {
       "enabled": false
   }

3. 现在，假设我们在 packages/analytics 中有一个由不同团队维护的新包。该团队遵循完全不同的编码标准，因此他们不希望从根配置继承选项。对于这些模块，只需从配置文件中省略 "extends": "//"，并更改格式化选项即可：

   ¥Now, let’s suppose we have a new package in packages/analytics that is maintained by a different team. This team follows entirely different coding standards, so they don’t want to inherit options from the root configuration. For them, they just need to omit "extends": "//" from the configuration file, and change the formatting options:

   packages/analytics/biome.json

   {
       "root": false,
       "formatter": {
           "lineWidth": 100,
       }
   }

4. 现在一切都已设置完毕，你可以选择以下几个选项。你可以从项目根目录或各个包运行 biome 命令。Biome 将遵循所有设置！

   ¥Now that everything is set up, you have a few options. You can run biome commands from the root of the project, or from the single packages. Biome will respect all settings!

Tip

有时，Biome 可能会发现某个嵌套的配置文件缺少正确的 "root": false 设置。例如，如果你有另一个项目在 vendored 文件夹或 Git 子模块中使用 Biome，则可能会发生这种情况。在这种情况下，我们建议完全忽略使用 files.includes 字段 的嵌套项目。

¥Sometimes, Biome may find a nested configuration file that doesn’t have a correct "root": false setting. This can happen if you have another project that uses Biome in a vendored folder or Git submodule, for instance. In such a case, we suggest ignoring the nested project entirely using the files.includes field.

共享配置文件的其他方式

¥Other ways to share a configuration file

如上所述，extends 字段允许你将配置拆分到多个文件中。这样，你可以在不同的项目或文件夹之间共享通用设置。当你希望嵌套配置继承自根配置时，"extends": "//" 语法是一个便捷的快捷方式，但有时你可能需要使用更加自定义的设置。

¥As we saw above, the extends field allows you to split your configuration across multiple files. This way, you can share common settings across different projects or folders. The "extends": "//" syntax is a convenient shortcut when you want nested configurations to extend from the root configuration, but sometimes you may want to use an even more customised setup.

除了 "//" 之外，extends 设置也接受数组值。在这种情况下，数组中的每个值都必须是要扩展的另一个配置的路径。

¥Apart from "//", the extends setting accept array values as well. In this case, every value in the array must be a path to another config to extend.

例如，以下是如何设置配置以扩展 common.json 配置文件的方法：

¥For example, here is how you might set up your configuration to extend a common.json configuration file:

biome.json

{
  "extends": ["./common.json"]
}

从定义 biome.json 文件的路径解析 extends 中定义的条目。它们按照列出的顺序进行处理，后面文件中的设置将覆盖前面的设置。

¥The entries defined in extends are resolved from the path where the biome.json file is defined. They are processed in the order they are listed, with settings in later files overriding earlier ones.

你使用 extend 引用的文件不能再使用 extend 引用其他文件。

¥Files that you extend from cannot extend other files in turn.

请注意，配置文件中的路径始终从 biome.json/biome.jsonc 文件所在的文件夹解析。使用 extends 字段时，这意味着共享配置中的路径是从扩展它的配置的位置解释的，而不是从被扩展文件的文件夹解释的。

¥Note that paths in a configuration file are always resolved from the folder in which the biome.json/biome.jsonc file resides. When using the extends field, this means that paths in a shared configuration are interpreted from the location of the configuration that is extending it, and not from the folder of the file being extended.

例如，假设一个项目包含两个目录 backend/ 和 frontend/，每个目录都有自己的 biome.json，它们都扩展了根文件夹中的 common.json 配置：

¥For example, let’s assume a project that contains two directories backend/ and frontend/, each having their own biome.json that both extend a common.json configuration in the root folder:

• Directory

  backend/

  • Directory

    src/

    • …
  • Directory

    test/

    • …

  • biome.json

• Directory

  frontend/

  • Directory

    src/

    • …
  • Directory

    test/

    • …

  • biome.json

• common.json

common.json

{
  "files": {
    "includes": ["src/**/*.js", "test/**/*.js"],
  },
  "linter": {
    "includes": ["**", "!test"]
  }
}

frontend/biome.json

{
  "extends": ["../common.json"]
}

• 从 frontend/ 文件夹运行 Biome 时，它​​将被配置为格式化和检查 frontend/src/ 和 frontend/test/ 文件夹中的所有 JavaScript 文件，并且仅格式化 frontend/src/ 文件夹中的文件。之所以有效，是因为 common.json 中指定的路径是从 frontend/ 文件夹解析的，因为 biome.json 文件就位于该文件夹中。

  ¥When running Biome from the frontend/ folder, it will be configured to format and lint all JavaScript files in the frontend/src/ and frontend/test/ folders, and only format the files in the frontend/src/ folder. This works because the paths specified in common.json are interpreted from the frontend/ folder, because that’s where the biome.json file resides.

• 假设 backend/biome.json 与 frontend/biome.json 看起来相同，它们的行为将相同，只是路径将从 backend/ 文件夹解析。

  ¥Assuming backend/biome.json looks the same as frontend/biome.json, it will have the same behaviour, except the paths will be interpreted from the backend/ folder.

请注意，在此设置中，frontend/biome.json 和 backend/biome.json 都被视为根配置。除非你使用 --config-path CLI 选项并将其指向某个配置，否则你将无法从存储库的根目录运行 Biome。

¥Note that in this setup, both frontend/biome.json and backend/biome.json are considered root configurations. You won’t be able to run Biome from the root of the repository, unless you use the --config-path CLI option and point it at one of the configurations.

从 NPM 导出 Biome 配置软件包

¥Exporting a Biome configuration from an NPM package

Biome 还能解析 node_modules/ 文件夹中的配置文件。这样你就可以从包中导出配置文件，并将其导入到多个项目中。

¥Biome is also able to resolve configuration files from the node_modules/ folder. So you can export your configuration file from a package, and import it in multiple projects.

为此，首先要做的是以某种方式设置 “shared” Biome 配置。假设你想使用说明符 @org/shared-configs/biome 共享来自名为 @org/shared-configs 的包的配置。你必须在此包的 package.json 中创建一个 exports 条目：

¥In order to do so, the first thing to do is to set up your “shared” Biome configuration in a certain way. Let’s suppose that you want to share a configuration from a package called @org/shared-configs, using the specifier @org/shared-configs/biome. You have to create an exports entry in the package.json of this package:

package.json

{
  "name": "@org/shared-configs",
  "type": "module",
  "exports": {
    "./biome": "./biome.json"
  }
}

确保 @org/shared-configs 已正确安装在你的项目中，并更新 biome.json 文件以使其看起来像以下代码片段：

¥Make sure that @org/shared-configs is correctly installed in your project, and update the biome.json file to look like the following snippet:

biome.json

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

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

¥Biome will attempt to resolve your library @org/shared-configs/ from your working directory. The working directory is:

• 使用 CLI 时，指的是你执行脚本的文件夹。通常它与你的 package.json 文件的位置相匹配；

  ¥when using the CLI, the folder where you execute your scripts from. Usually it matches the location of your package.json file;

• 使用 LSP 时，指的是你的项目根文件夹。

  ¥when using the LSP, the root folder of your project.

Caution

以点号 . 开头或以 .json 或 .jsonc 结尾的路径始终被视为相对路径，因此它们不会从 node_modules/ 解析。

¥Paths starting with a dot . or ending with .json or .jsonc are always treated as relative paths, so they won’t be resolved from node_modules/.

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

¥For more information about the resolution algorithm, refer to the Node.js documentation.