Zenn
🌀

Biome の導入と設定方法まとめ

2024/04/13に公開
JavaScript
TypeScript
ESLint
Biome
tech

徐々に利用者が増えている Biome の自分向け技術メモの共有です。導入の仕方やよく触る設定周りなど、自身がよく見返したり他者に説明する部分を抽出してまとめてあります。

実際に自身が利用した感想は以下の通りです。

  • pros
    • 速さはとにかく正義
    • 必要十分な lint ルールはあると感じた
    • 設定もわかりやすく職人になりにくい
  • cons
    • ライブラリが提供してくれるライブラリのベストプラクティスを反映した eslint plugin が利用できない
    • eslint 及び eslint plugin と比較するとルールは少ないので得られる学びは少なくなる

特に速さに関しては eslint だとプロジェクト規模が大きくなったり追加したルールが増えてくると開発効率に影響あるレベルで時間がかかるようになったので、これを解消できた点が大きかったです。

Biome とは

Biome
Rome という JavaScript/TypeScript を中心とした Web 開発に必要な多くのツールを 1 つに集約する事を目指したプロジェクトがあり会社を立ち上げ開発されていたのですが、会社の経営悪化などによりコアメンバーが解雇され開発が停滞する状況になりました。Biome はそのコアメンバー達が fork して再始動した開発ツールのプロジェクトです。

目標や思想は同じく Web 開発に必要なツール郡を Rust 製の高速で少ない設定で動くツールに集約しようといったもので、記載時点では format と lint を行う機能が提供されています。

インストール

はじめる | Biome
バージョニング | Biome

pnpm add -D --save-exact @biomejs/biome

"^1.0.0" 等の範囲指定だと予期せぬタイミングでバージョンアップが行われて lint や format の仕様変更が入り、CI 等が失敗するようになってしまうので固定する事が推奨されています。

初期設定

はじめる | Biome

pnpm exec biome init

プロジェクトのルートディレクトリで上記のコマンドを実行し設定ファイルである biome.json を生成します。デフォルトでは import のソート、format, 推奨ルールを使った lint が有効になっていますので、適切好みの設定に調整してください。

実行方法

はじめる | Biome
CLI | Biome

# format
pnpm biome format --write ./src
# lint (check only)
pnpm biome lint ./src
# lint fix
pnpm biome lint --apply ./src
# organize import, format, lint
pnpm biome check --apply ./src

利用頻度の高いコマンドは上記の通りです。

./src の部分はファイル or ディレクトリ or globパターンが指定可能です。複数の対象を指定したい場合はスペース区切りで指定できます。対象ファイルや除外ファイルを制御したい場合は設定ファイルで行えます。

Lint

Linter | Biome
Lint Rules | Biome
Configuration#Linter | Biome

biome init で生成されるデフォルトの設定は以下の通りです。

{
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true
    }
  }
}

Lint のルール設定は all と recommended という一括設定する方法と個別に設定する方法が用意されています。all と recommended は名前の通りで全て or 推奨設定が有効化され、個別設定と併用が可能なので all を使いつつ一部のルールを無効化したりできます。

{
  "linter": {
    "enabled": true,
    "rules": {
      "all": true,
      "suspicious": {
        "noExplicitAny": "off"
      }
    }
  }
}

対象や除外の設定は以下のように include と ignore で行えます。

{
  "linter": {
    "include": ["src/**/*.{js,jsx,ts,tsx}"],
    "ignore": ["**/node_modules/**"]
  }
}

行単位の無効化

Linter#Ignoring Code | Biome

// biome-ignore lint: reason
// biome-ignore lint/suspicious/noDebugger: reason

eslint ではファイル単位などコメントで無効化する方法が複数ありましたが、Biome では次の行の lint を無効化するコメントのみ(記載時点)となっています。上記の一行目が全ての lint ルールを無効化する方法で、二行目が特定のルールを無効化する方法です。reason の部分は無効化する理由を書く場所で省略可です。

Format

Formatter | Biome

デフォルトの設定は以下の通りです。Biome はデフォルトで format が以下の内容で有効になっており、biome init で生成される設定には出力されないので注意して下さい。
organizeImports は import のソート機能のことで、Biome の定義上では Analyzer に含まれるのですが format と合わせて設定する事が多いので一緒に紹介しています。

{
  "organizeImports": {
    "enabled": true
  },
  "formatter": {
    "enabled": true,
    "formatWithErrors": false,
    "indentStyle": "tab", // or "space"
    "indentWidth": 2,
    "lineWidth": 80,
    "include": [],
    "ignore": []
  }
}

organizeImports と formatter のそれぞれに include と ignore が設定できます。

{
  "organizeImports": {
    "include": [],
    "ignore": []
  },
  "formatter": {
    "include": [],
    "ignore": []
  }
}

Configuration#json | Biome
Configuration#javascript | Biome
format は上記の共通設定以外に json と javascript に対して個別の設定や特有の設定を行う事ができます。

好みの JavaScript の設定を残しておきます。

{
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "jsxQuoteStyle": "single",
      "semicolons": "asNeeded"
    }
  }
}

行単位の無効化

// biome-ignore format: reason

Lint の無効化と同じく上記のコメントで次の行の format を無効化できます。

設定と振る舞い

Biome の振る舞い | Biome

Biome はコマンドを実行したディレクトリを起点に順番に遡りながら設定ファイル biome.json を探します。見つかれば探索はそこで終了しその設定を適用します。見つからなければデフォルトの設定が適用されます。

大きなプロジェクトでのBiomeの使用方法 | Biome
設定を共有したい場合は extends を使って行なえます。

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

Biome の振る舞い#既知のファイル | Biome
package.json など一部のファイルはデフォルトで無視されるようになっています。

monorepo で vscode extension 利用時の注意点

VSCode拡張機能 | Biome
導入の仕方や設定は公式の通りなので省略し、monorepo を採用したプロジェクトで利用時の注意点があるので、それについて触れておきます。

これも公式ページに書いてはあるのですが、拡張機能は Biome の実行ディレクトリが常に vscode のワークスペースのルートディレクトリとなり、ルートディレクトリにある biome.json しか読み取ってくれません。

monorepo 採用時に開く vscode のワークスペースは恐らく monorepo のワークスペースのルートに合わせて開く事が多いと思うのですが、上記の振る舞いの影響で各パッケージ毎に置いた biome.json の設定は読み取ってくれません。これにより CLI 上で実行したコマンドや Git 等のフックでは問題なくても vscode 上でファイルを開くと lint エラーが表示されるなどが起きてしまいます。

私が把握している現状取れる対策は以下の通りです。

  • monorepo ルートの biome.json でも支障がない設定ならここに書く
  • 各パッケージをルートとして vscode で開く

もし他に取れる対策をご存じの方がいらっしゃいましたら教えて頂けると助かります。

参考

Discussion