Biome v1

Aug 29, 2023 - 10 min read

Emanuele Stoppa

Biome Core Team

在 Biome v1 中，格式化程序提供了箭头函数中 JSX 引号和括号的选项；CLI 新增了命令 biome lint，支持 .jsonc 文件，并且可以扩展配置文件。

¥In Biome v1, the formatter has options for JSX quotes and parentheses in the arrow functions; the CLI adds a new command biome lint, .jsonc files are supported, and it’s possible to extend the configuration file.

你可以通过运行以下命令来升级 Biome：

¥You can upgrade Biome by running the following command:

npm install --save-dev --save-exact @biomejs/biome@1.0.0
pnpm update --save-exact @biomejs/biome@1.0.0
yarn upgrade --exact @biomejs/biome@1.0.0

或者安装 VS Code 扩展 将 Biome 集成到你的编辑器中。

¥Or install the VS Code extension to integrate Biome into your editor.

新增格式化选项

¥New formatter options

Biome 现在支持两个期待已久的新选项：

¥Biome now supports two new, long-awaited options:

• 支持 JSX 中首选引号的格式化；

  ¥support for formatting the preferred quote kind in JSX;

• 仅在需要时才支持箭头函数中的括号格式化。

  ¥support for formatting parenthesis in arrow functions only when they are needed;

JSX 引号样式

¥JSX quotes style

你可以通过 CLI 或 biome.json 文件使用此选项：

¥You can use this option via CLI or via biome.json file:

biome.json

{
  "javascript": {
    "formatter": {
      "jsxQuoteStyle": "single"
    }
  }
}

biome format --jsx-quote-style=single --write ./src

Biome 将在 JSX 代码中定义属性时使用单引号：

¥And Biome will apply single quotes when defining attributes in JSX code:

import Item from "./item.jsx";

const Header = () => {
  return <Item title="Docs" />;
};

箭头函数括号

¥Arrow function parenthesis

你可以选择不打印箭头函数中的括号。你可以通过 CLI 或 biome.json 自定义此选项：

¥You can decide not to print parenthesis in arrow functions. You can customize the option via CLI or via biome.json:

biome.json

{
  "javascript": {
    "formatter": {
      "arrowParentheses": "asNeeded"
    }
  }
}

biome format --arrow-parentheses=as-needed --write ./src

Biome 只会在需要括号的箭头函数中打印括号：

¥And Biome will print parenthesis only for those arrow functions that require them:

// no need for parentheses
const filter = (term) => {};
// needs parentheses
const filterBy = (term, fn) => {};

CLI 改进

¥CLI improvements

CLI 经过大量重构，以确保在处理文件、诊断信息和命令时行为一致。

¥The CLI was heavily reworked to guarantee consistent behaviour when handling files, diagnostics emitted and commands.

这些更改中包​​含一些破坏性的行为变更。

¥Among those changes, there are some breaking changes in its behaviour.

• 如果配置文件包含错误，CLI 将以错误代码退出。虽然 Biome 可以成功解析配置。 - 即使有错误 - 这对我们的用户来说是一个隐患。配置文件中的拼写错误会导致 Biome 应用其默认值，并使 Biome 的执行行为与用户设置的行为不同。

  ¥The CLI exits with an error code if the configuration file contains errors; while Biome can parse the configuration successfully - even with errors - this was a hazard for our users. A typo in the configuration file would have resulted in Biome applying its defaults, and executing Biome with a different behaviour compared to the one set by the user.

• 命令 biome check 现在会对未格式化的代码发出错误诊断信息，并以错误代码退出。此行为符合此命令的语义预期。

  ¥The command biome check will now emit error diagnostics for code not formatted and exits with an error code. This behaviour aligns with the semantics meant for this command.

新增 biome lint 命令

¥New biome lint command

命令 biome check 旨在运行多个工具，这有时会让用户感到不知所措。启用 biome lint 后，Biome 将仅对文件运行代码检查规则。

¥The command biome check is meant to run multiple tools, which sometimes can overwhelm the users. With biome lint, Biome will only run lint rules against files.

目前，该命令几乎支持 biome check 的所有命令行参数。未来，此命令将针对代码检查进行专门化和调整。

¥As for now, the command accepts almost all the CLI arguments of the biome check. In the future, this command will specialize and tweak its behaviour around linting.

对错误有更多控制

¥More control over errors

默认情况下，当 Biome 检测到无法处理的文件时，它会触发诊断信息并以错误代码退出。

¥By default, when Biome sees a file that can’t handle, it fires a diagnostic and will exit with an error code.

启用 --files-ignore-unknown 选项后，命令行接口 (CLI) 将不再输出诊断信息，并继续处理文件。

¥With --files-ignore-unknown option, the CLI won’t emit diagnostics and will continue processing files.

你也可以在 biome.json 中定义此行为：

¥You can define this behaviour in the biome.json too:

biome.json

{
  "files": {
    "ignoreUnknown": true
  }
}

当 Biome 在执行命令期间无法处理文件时，它会以错误代码退出并发出错误诊断信息。

¥When Biome doesn’t process files during a command, it exits with an error code and emits an error diagnostic.

现在，使用 --no-errors-on-unmatched，Biome 将成功运行代码，并且不会发出任何诊断信息。

¥Now, with --no-errors-on-unmatched, Biome will exist with a successful code and doesn’t emit any diagnostics.

此新选项允许用户将 Biome 与 lint-staged 等工具一起使用。

¥This new option allows users to use Biome with tools like lint-staged.

出现警告时退出

¥Exit on warnings

在 Biome 中，你可以更改规则的配置，并允许它们发出诊断信息。此行为之前存在局限性，现在借助 --error-on-warnings 选项，你可以指示 Biome 在发出警告时以错误代码退出。

¥In Biome, you can change the configuration of rules and allow them to emit diagnostics. This behaviour was limited, and now with --error-on-warnings option, you can tell Biome to exit with an error code if a warning is emitted.

以下是一个示例，让我们通过 biome.json 更改规则的诊断级别：

¥Here’s an example, let’s change the diagnostic level of a rule via biome.json:

biome.json

{
  "linter": {
    "recommended": true,
    "rules": {
      "a11y": {
        "useAltText": "warn"
      }
    }
  }
}

以下是触发此规则的示例代码：

¥Here’s a sample code that will trigger the rule:

const Image = () => {
  return <img src="https://example.com/image.png" />;
};

现在，使用新选项运行 CLI：

¥And now, run the CLI using the new option:

biome lint --error-on-warnings ./src

JSONC 支持和注释

¥JSONC support and comments

Biome 的 JSON 解析器现在支持注释，因此我们启用了这些令人兴奋的新功能。

¥Biome’s JSON parser now supports comments, so we enabled these exciting new features.

.jsonc 文件支持

¥.jsonc file support

Biome 现在可以格式化和检查 .jsonc 文件。

¥Biome can now format and lint .jsonc files.

允许在 JSON 文件中添加注释

¥Allow comments in JSON files

Biome 可以解析 JSON 文件中的注释。你可以通过配置文件启用此功能：

¥Biome can parse comments inside JSON files. You can opt-in to this feature via the configuration file:

biome.json

{
  "json": {
    "parser": {
      "allowComments": true
    }
  }
}

Note

biome.json 文件不允许包含注释。

¥The biome.json file doesn’t allow comments.

Caution

启用此功能后，Biome 遇到的所有 JSON 文件中都允许添加注释。

¥When enabling this feature, comments will be permitted in all JSON files encountered by Biome.

此外，Biome 现在可以识别一些已知文件为 “支持带注释的 JSON 文件”。例如，现在 Biome 可以格式化带有注释的 tsconfig.json 文件而不会报错！

¥Plus, Biome now recognizes some known files as “JSON files that can have comments”. For example, now Biome can format your tsconfig.json file with comments without emitting errors!

extends 属性

¥extends property

现在，你可以将配置文件拆分为多个文件，并使用新的 extends 属性将它们合并。

¥You can now break down your configuration file into different files and join them using the new extends property.

biome.json

{
  "extends": ["./formatter.json", "./linter.json"]
}

查看 documentation 以了解其工作原理。

¥Check the documentation to understand how it works.

Linter

我们删除了两条规则：

¥We deleted two rules:

• useCamelCase，已被 useNamingConvention 取代；

  ¥useCamelCase, which is replaced by useNamingConvention;

• 无需 noExtraSemicolon；格式化程序会处理它；

  ¥noExtraSemicolon, not needed; the formatter takes care of it;

新增规则

¥New Rules

• noDuplicateJsonKeys

  此规则禁止 JSON 对象中存在重复键。

  ¥This rule disallows duplicate keys in a JSON object.

• noExcessiveComplexity

  此规则计算复杂度得分，并报告得分高于可配置阈值的代码。

  ¥This rule computes a complexity score and reports code with a score above a configurable threshold.

• noFallthroughSwitchClause

  此规则禁止 switch 情况延续到下一个 case 情况。

  ¥This rule disallows switch cases that fall through to the next case.

• noGlobalIsFinite

  此规则建议使用 Number.isFinite 代替全局且不安全的 isFinite（isFinite 会尝试类型强制转换）。

  ¥This rule recommends using Number.isFinite instead of the global and unsafe isFinite that attempts a type of coercion.

• noGlobalIsNan

  此规则建议使用 Number.isNaN 代替全局且不安全的 isNaN（isNaN 会尝试类型强制转换）。

  ¥This rule recommends using Number.isNaN instead of the global and unsafe isNaN that attempts a type of coercion.

• noNonoctalDecimalEscape

  此规则禁止在字符串字面量中使用 \8 和 \9 转义序列。

  ¥This rule disallows \8 and \9 escape sequences in string literals.

• noUnsafeDeclarationMerging

  此规则禁止在接口和类之间合并声明。

  ¥This rule disallows declaration merging between an interface and a class.

• noUselessEmptyExport

  此规则禁止使用无用的 export {}。

  ¥This rule disallows useless export {}.

• noUselessThisAlias

  此规则禁止在箭头函数中使用无用的 this 别名。

  ¥This rule disallows useless aliasing of this in arrow functions.

• noVoid

  此规则禁止使用 void。

  ¥This rule disallows the use of void.

• useArrowFunction

  此规则建议将函数表达式转换为箭头函数。使用 this 的函数表达式将被忽略。

  ¥This rule proposes turning function expressions into arrow functions. Function expressions that use this are ignored.

• useGetterReturn

  此规则强制 get 方法始终返回一个值。

  ¥This rule enforces get methods to always return a value.

• useImportRestrictions

  启用对本地导入方式的限制。

  ¥Enables restrictions on how local imports should be imported.

• useIsArray

  此规则建议使用 Array.isArray() 代替 instanceof Array。

  ¥This rule proposes using Array.isArray() instead of instanceof Array.

• useNamingConvention

  该规则强制在整个代码库中使用通用的 JavaScript 和 TypeScript 命名约定。

  ¥The rule enforces wide-spread naming conventions of Javascript and TypeScript across a codebase.

已推广规则

¥Promoted rules

新规则已发布，请查看 #4750 了解更多详情：

¥New rules are promoted, please check #4750 for more details:

• suspicious/noDuplicateJsxProps

• suspicious/noConsoleLog

• correctness/useIsNan

• complexity/useSimpleNumberKeys

• complexity/useLiteralKeys

• complexity/noForEach

• a11y/useHeadingContent

以下规则现已推荐：

¥The following rules are now recommended:

• useExponentiationOperator

• noUselessFragments

• noRedundantUseStrict

支持函数类参数装饰器

¥Support for function class parameter decorators

在上一个版本中，Biome 引入了对 Stage 3 装饰器的支持。尽管最终提案不支持函数类参数装饰器：

¥In the last release, Biome introduced support for Stage 3 decorators. Although, this final proposal doesn’t support the function class parameter decorators:

class Controller {
    get(@Param("id") id: string) {}
    // ^^^^^^^^^^^^ syntax not covered by the official and final decorators spec
}

部分用户不满，因为他们无法在 Angular/NestJS 项目中使用 Biome。现在，你可以通过配置来实现：

¥Some users were dissatisfied because they couldn’t use Biome inside their Angular/NestJS project. Now you can do it via configuration:

biome.json

{
  "javascript": {
    "parser": {
      "unsafeParameterDecoratorsEnabled": true
    }
  }
}

致谢

¥Acknowledgements

非常感谢以下贡献者：

¥Big thank you to the following contributors:

• denbezrukov，他们实现了新的装饰器参数、格式化程序中的新选项 jsxQuoteStyle，并开始开发新的 CSS 解析器；

  ¥denbezrukov, they implemented the new decorator parameter, the new option jsxQuoteStyle in the formatter, and started the works for our new CSS parser;

• Conaclos，他们继续创建新规则，使现有规则更加智能，并为 Biome 添加了大量价值；

  ¥Conaclos, they continued creating new rules, making the existing ones smarter and adding tons of value to Biome;

• SuperchupuDev，他们在格式化程序中实现了新选项 arrowParentheses；

  ¥SuperchupuDev, they implemented the new option arrowParentheses in the formatter;

• nissy-dev，他们修复了代码检查器中的许多问题；

  ¥nissy-dev, they fixed a bunch of issues around the linter;

• unvalley，他们修复了代码检查器中的许多问题并实现了新规则；

  ¥unvalley, they fixed a bunch of issues around the linter and implemented new rules;

• arendjr，他们在代码检查器中实现了新规则，并实现了新的导入排序策略；

  ¥arendjr, they implemented new rules in the linter and implemented the new import sorting strategy;

• ddanielsantos，对于他们首次对项目做出的贡献；

  ¥ddanielsantos, for their first contribution to the project;

• nikeee，对于他们首次对项目做出的贡献；

  ¥nikeee, for their first contribution to the project;

翻译

¥Translations

• 中文翻译:Biome v1 版本

  ¥中文翻译: Biome v1版本

Biome 格式化程序赢得 Prettier 挑战赛

发布 Biome