biomejs/biome
github.com/biomejs/biome ↗ · 3991 files · 21.1 MB · scan capped
[![CI on main][ci-badge]][ci-url] [![Discord chat][discord-badge]][discord-url] [![npm version][npm-badge]][npm-url] [![VSCode version][vscode-badge]][vscode-url] [![Open VSX version][open-vsx-badge]][open-vsx-url] [ci-badge]: https://github.com/biomejs/biome/
Overview
Biome is a Rust toolchain (formatter, linter, and language services) for JavaScript, TypeScript, JSON, CSS, GraphQL, HTML, and related languages, shipped as a CLI, an LSP, and npm packages. The workspace at commit 82f9b0e6 is versioned 0.7.0 in the root Cargo manifest and published primarily as @biomejs/biome. Distinctive pieces are the shared CST/parser stack, rule and assist registries, a daemon, and generated configuration and bindings.
System map
The Rust workspace lives under crates/ with the biome binary in crates/biome_cli. Language crates (parser, formatter, analyzer, semantic model) sit beside shared infrastructure (biome_service, biome_configuration, biome_lsp, biome_fs, biome_rowan). Node consumers are in packages/@biomejs/biome, @biomejs/js-api, and @biomejs/backend-jsonrpc. Build and test entry points are Cargo, justfile recipes, pnpm workspace scripts, and GitHub Actions on main. Persistence is mostly the filesystem (biome.json, file system trait, daemon socket) rather than a database.
- Root Cargo.toml names the workspace biome at version 0.7.0, uses resolver 2, and excludes fuzz and benchmark packages from the default members.
- The published CLI crate is crates/biome_cli (package name biome, version 0.0.0 in-tree). Its binary entry is src/main.rs, which calls biome_cli::run_server unless BIOME_LOG_PATH is set, in which case it initializes env_logger from that directory.
- Supported document languages are enumerated as JavaScript, Json, Jsonc, Css, Graphql, Html, Grit, Tailwind, Yaml, Svelte, and Vue in DocumentFileSource.
- Configuration is modeled in biome_configuration (package version 0.0.1 in-tree, described as biome_json in the scan inventory). Schema and partial types are generated; users typically commit biome.json or biome.jsonc.
- The Node package @biomejs/biome is a platform-specific binary wrapper. The monorepo root package.json is private, named @biomejs/monorepo, and delegates test/lint/format to just and cargo.
- pnpm-workspace.yaml includes packages/* and packages/@biomejs/*. npm publishing and WASM/JSON-RPC backends are separate packages from the Rust CLI.
- CI on push/PR is .github/workflows/main.yml. It runs Rust tests, lint, format checks, and related jobs. Autofix for generated artifacts is a separate workflow.
- There is no application database. File IO goes through biome_fs (OsFileSystem, MemoryFileSystem) and configuration files on disk. The daemon uses a local socket via biome_lsp_factory / biome_service daemon modules.
- Fuzz targets live in fuzz/ (cargo package names still carry historical rome_* names such as the typescript formatter fuzzer) and are excluded from the main workspace members.
Feature catalog
User-facing surfaces are the biome CLI, the LSP used by editors, the migrate/eslint path, the daemon, and the npm/WASM JS API. Analysis features are lint rules, assists, and syntax rules registered per language. Format, check, lint, ci, and search are the everyday commands. Plugins (Grit) and HTML/Vue/Svelte/Tailwind are first-class language frontends.
- biome init writes a starter configuration. biome migrate rewrites Biome, ESLint, Prettier, and related configs. biome explain prints rule documentation. biome search runs structured search (GritQL-backed).
- JavaScript and TypeScript lint rules are split into groups (a11y, complexity, correctness, nursery, performance, security, style, suspicious, and others) under crates/biome_js_analyze/src/lint.
- CSS, JSON, GraphQL, HTML, and GraphQL-adjacent analyzers have their own crates (biome_css_analyze, biome_json_analyze, biome_graphql_analyze, biome_html_analyze) registered through the service feature set.
- Formatters exist per language: biome_js_formatter, biome_json_formatter, biome_css_formatter, biome_graphql_formatter, biome_html_formatter, plus embedded Tailwind and YAML handling.
- ESLint migration preserves selected rule options through source-option models, not only severity. The eslint-migrate skill and migrate command implement that path.
- The JS API package exposes WASM and a JSON-RPC backend that talks to the daemon. @biomejs/backend-jsonrpc is the client for that socket.
Data flow
Input is a filesystem path plus biome.json. The CLI or LSP opens a Workspace, scans projects, classifies each file by extension and embedded language, then parses to a Rowan CST. Settings (formatter, linter, assist, overrides, plugins) are merged from configuration and VCS ignore data. Analyzers and the formatter consume the CST and optional semantic or type information. Diagnostics and code actions return to the CLI printer, the LSP, or the JSON-RPC/WASM boundary. Fixes can be written back through the FileSystem trait.
- File classification starts in file_handlers: extension and language directives choose DocumentFileSource, then a language-specific parser builds the CST.
- biome_parser and biome_rowan own the green-tree representation shared by every language. Syntax nodes are cheap handles into an immutable tree; text is recovered from tokens.
- Configuration load path: locate biome.json or biome.jsonc, deserialize into biome_configuration types, merge extends and overrides, then push Settings into the workspace. VCS (Git) ignore rules further filter the file set.
- Lint execution goes through biome_analyze: a RuleRegistry matches query types against the syntax tree (and semantic events). Each rule emits RuleDiagnostic or a code action.
- The formatter lowers CST to a format IR (biome_formatter) and prints with options from configuration (indent, line width, quote style). Language crates implement FormatNode rules.
- Type-aware rules use Salsa-backed inference in biome_js_type_info and biome_module_graph rather than only syntactic matching. The workspace requests inferred types for a module.
- Stdin mode treats unnamed input as a virtual document. The CLI still routes it through the same parse, lint, and format pipeline and prints the result instead of writing a path.
- Fixes and assists mutate the CST via biome_rowan batches or text edits, then the workspace writes the new source through FileSystem. Unsafe fixes are gated by CLI flags and rule fix kind.
Behavior traces
Three load-bearing flows are process startup into the CLI dispatcher, a check/lint pass over a project, and configuration plus fix persistence. A fourth adjacent flow is LSP or daemon startup, which reuses WorkspaceServer instead of one-shot CLI traversal. Function names below are the ones present in the crates read for this brief.
- Startup: main in crates/biome_cli/src/main.rs reads BIOME_LOG_PATH, optionally initializes a log file, then calls biome_cli::run_server (or the pavilion entry used by the binary). Panic hook is installed before argument parsing.
- Parse step inside a language handler: the file handler calls the language parser (for JS, parse_module or parse_script in biome_js_parser), producing a Parse result that carries both the CST and parse diagnostics.
- Lint step: the analyzer pulls rules from the language registry (for example biome_js_analyze::rules), filters by configuration severity and nursery or recommended sets, then visits the tree. Matching rules call diagnose.
- Format step: the language formatter builds a FormatElement IR from the CST and prints it with biome_formatter::Printed. If the printed text differs, a format diagnostic or write-back is produced.
- Persistence of fixes: when --write or --fix is set, the workspace applies text edits and calls FileSystem::open or write. Without those flags the process only reports. Configuration itself is not rewritten except by biome init and biome migrate.
- Init flow: biome init detects an existing config, prompts or writes biome.json with default formatter and linter sections, and can import from Prettier or ESLint when migrate is used instead.
- Migrate flow: read the foreign config (eslint.config or .eslintrc, prettier), map rules through generated and hand-written converters, emit a Biome configuration and a report of unmapped rules.
Testing signals
Rust tests use the built-in harness plus insta snapshots and codegen-driven spec tests. Language crates keep tests/specs directories with input files and expectation comments. The JS API uses Vitest. GitHub Actions runs the Rust suite, parser conformance, and autofix. Coverage is dense on parsers, formatters, and lint rules, and thinner on daemon lifecycle and editor integration.
- Crate tests are invoked with cargo test or just test. A single crate is just test-crate <name>. Doctests are just test-doc. CONTRIBUTING.md documents these commands.
- Snapshot testing uses insta. Failing snapshots are reviewed with cargo insta accept, reject, or review. Formatter and lint tests often commit .snap files next to specs.
- Lint and assist fixtures follow a spec layout: a source file with biome-ignore or expect comments, generated by macros in biome_analyze and exercised by the language test harness. The testing-codegen skill documents quick_test and orphan checks.
- Parser tests compare against Test262, Babel, TypeScript, and Prettier corpora. The parser_conformance workflow fails the build when those suites regress.
- Fuzzing is a separate Cargo workspace under fuzz/ with cargo-fuzz targets for parsers and the formatter. It is not part of the default cargo test run.
- packages/@biomejs/js-api tests run under Vitest (the repo's stack tags and package scripts). They require a prior WASM or JSON-RPC build, so they do not run from cargo test alone.
- CLI behavior is tested in crates/biome_cli/tests with fixture projects (configuration, lint, format, migrate). These spawn the library entry rather than only unit-testing parsers.
- main.yml is the merge gate for Rust fmt, clippy, and test. autofix.yml regenerates bindings and schema when codegen drifts. lint_rule_docs.yml checks rule documentation.
- Formatter idempotency and Prettier comparison tests live beside biome_js_formatter and related crates. A format change is expected to update snapshots, not only assertions.
- Type-inference tests cover Salsa invalidation and module cycles in biome_js_type_info and biome_module_graph. Many syntax-only rules do not enable the type engine in their fixtures.
- Agents.md requires just f and just l before commit, plus the current crate's tests. User-facing changes also need a changeset under .changeset.
Risk map
The highest-risk surfaces are the daemon socket, arbitrary filesystem reads during project scan, shell-free but powerful code actions that rewrite user trees, and the migrate command that ingests third-party configs. Generated registries mean a hand edit can be overwritten. Type inference and the service layer are blast-radius hotspots: a small change can break every language. Secrets are not a primary domain; the tool still reads every file the user points it at.
- The daemon listens on a local socket and executes workspace operations for connecting clients. A local process that can connect can request lint, format, and file reads of the project the daemon was started in.
- biome rage prints configuration, environment, and paths to help bug reports. It can leak local paths and config contents if users paste the output.
- Code actions and --write mutate source files in place. Unsafe fixes are distinguished from safe ones in the analyzer, but a wrong fix kind still rewrites user code when the flag is passed.
- Migrate parses ESLint and Prettier configs from the target project. It does not evaluate arbitrary JavaScript plugins the way ESLint does, but it does read and rewrite configuration files.
- biome_service and biome_analyze are blast-radius hubs. Registry, settings, and file-handler changes affect every language CLI command and the LSP.
- Historical Rome names remain in fuzz package metadata and some comments. Treating those crates as the current product name will point agents at the wrong APIs.
- Salsa type queries cache aggressively. A query that captures the wrong revision or ignores file invalidation will make type-aware rules report stale results. The type-inference skill calls this out as a dedicated test surface.
- Logging via BIOME_LOG_PATH writes logs under a user-controlled directory. The CLI creates that directory from the environment variable at startup.
- CI and release workflows can publish npm binaries and crates. A mistaken change to package metadata or the release workflow has distribution blast radius beyond the compiler.
Extension points
New behavior is expected to plug in through language crates, declare_lint_rule and declare_assist macros, the analyzer registry, file handlers, configuration partials, CLI command enums, and Grit plugins. Codegen must be re-run when names or grammar change. The JS API is a consumer of the workspace, not the place to add languages.
- Lint rules are added with declare_lint_rule! in the language analyze crate, then listed in the group module (a11y, style, nursery, and so on) so the registry macro exports them.
- Assists use declare_assist_rule! and a parallel registry. Renaming a rule or assist requires just gen-rules and just gen-configuration.
- New syntax starts in an .ungram grammar, then just gen-grammar <lang> and just gen-formatter. Parser rules and formatter IR must be updated together.
- A new language frontend needs a parser crate, a formatter, an analyzer, a file handler arm in biome_service, and a DocumentFileSource variant. Registration is centralized, not discovered by directory scan.
- Rule options flow from JSON configuration through generated partial structs in biome_configuration into the rule's options type. New options require the configuration macros and schema codegen.
- ESLint option migration is an extension table: each supported rule has a source-option model and a converter. Unsupported rules are reported rather than guessed.
- Diagnostics are an extension surface. Categories, severity, markup, and advices are built with biome_diagnostics and biome_console, not ad-hoc strings.
- npm distribution adds a platform package under packages/@biomejs rather than changing the Rust entry. WASM exports are generated with wasm-bindgen.
Contributor handoff
Read AGENTS.md and the relevant skill under .claude/skills before editing. Keep diffs small, add a failing test for bug fixes, and do not hand-edit generated registries. Run the crate's tests, then just f and just l before commit. User-facing changes need a changeset; PR prose is written by the human, not the agent. Internal dev-dependencies must use path dependencies.
- First files for any task: AGENTS.md, CONTRIBUTING.md, and the skill that matches the surface (lint-rule-development, parser-development, formatter-development, testing-codegen, changeset, doc-comments).
- Safe edit boundary: change the language crate that owns the behavior and its tests. Do not drive a formatter fix only through snapshots, and do not change biome_rowan unless the CST model itself is wrong.
- Bug fixes need a spec or unit test that fails without the fix. Lint fixtures use expectation comments. Formatter changes update insta snapshots only after the behavior is reviewed.
- After a rule or assist rename, run just gen-rules and just gen-configuration. After an .ungram edit, run just gen-grammar <lang> and just gen-formatter. Bindings can be left to CI autofix unless local verification needs them.
- Verification commands: cargo test -p <crate> or just test-crate <crate>, then just f and just l. Full just ready is codegen for the whole repo and is slow.
- Comments and rustdoc must follow doc-comments. Lint rustdoc inside declare_lint_rule! is end-user documentation and also follows the lint-rule guide. Do not narrate the PR in comments.
- User-facing behavior needs a changeset created with just new-changeset, targeting @biomejs/biome. Patch goes to main; minor or major features and nursery promotions that affect users target next. Internal refactors do not get a changeset.
- Do not write PR descriptions. Preserve .github/PULL_REQUEST_TEMPLATE.md. If a PR is opened, disclose AI assistance. Conventional commit titles are required.
- Dev-dependencies on internal crates use path = "../biome_*", never workspace = true. Regular dependencies keep workspace = true.
- Trap: nursery rules use version metadata "next" until release. Promoting a rule is a branch and versioning decision, not only a group move.
- Trap: syntax text must not assume token text is contiguous UTF-8 without the syntax-text-handling rules. TokenText and range APIs exist because trivia and embedded languages break naive slices.
- Review gate: after implementation, a fresh subagent runs biome-code-review with only the scope and requirements, not suspected bugs. Actionable findings are fixed and verification is repeated.
Languages
| Language | Files | Share of source |
|---|---|---|
| Rust | 4732 | 40% |
| JavaScript | 3256 | 27% |
| TypeScript | 1933 | 16% |
| Markdown | 1378 | docs/config |
| JSON | 1348 | docs/config |
| Svelte | 751 | 6% |
| CSS | 739 | docs/config |
| YAML | 575 | docs/config |
Start reading here
Probable source entrypoint: Cargo.toml — inferred from the directory tree and manifest, not the upstream docs.
Source roots
crates/ (3593 files) packages/ (139 files)
Source layout — crates/
| Path | Files |
|---|---|
crates/biome_analyze/ | 2 |
crates/biome_analyze_macros/ | 2 |
crates/biome_aria/ | 2 |
crates/biome_aria_metadata/ | 2 |
crates/biome_cli/ | 250 |
Repository structure
| Top-level path | Files |
|---|---|
crates/ | 3593 |
packages/ | 139 |
xtask/ | 104 |
.github/ | 39 |
fuzz/ | 22 |
e2e-tests/ | 20 |
.claude/ | 17 |
.changeset/ | 17 |
Docs found: AGENTS.mdCLAUDE.mdCONTRIBUTING.mdREADME.md
Package
Cargo.toml — v0.7.0, 0 declared dependencies.
CI & config entrypoints
README.md— Repository readmeAGENTS.md— Agent instructionsCLAUDE.md— Claude instructions.github/workflows/actions_linter.yml— GitHub Actions workflow.github/workflows/autofix.yml— GitHub Actions workflow.github/workflows/benchmark.yml— GitHub Actions workflow.github/workflows/beta.yml— GitHub Actions workflow.github/workflows/beta_js_api.yml— GitHub Actions workflow.github/workflows/close-issue.yml— GitHub Actions workflow.github/workflows/labels.yml— GitHub Actions workflow
Structural health signals
Average score 7.7/10 across 96 analyzed source files; 22 hotspots surfaced.
xtask/codegen/src/formatter.rs— 959 lines, score 4.7 (Large file, Deep nesting)xtask/codegen/src/generate_global_types/lower/declarations.rs— 1177 lines, score 5 (Large file, Deep nesting)xtask/codegen/src/generate_nodes.rs— 1217 lines, score 5 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
82f9b0e6ff4b2026-09-21 — feat(type_info): lower the Math global class (#11857)09d18d49df272026-09-21 — chore(deps): update dependency @types/node to v24.13.5 (#11865)db9c853e919f2026-09-21 — chore(deps): update dependency tombi to v1.5.5 (#11866)2cdd220cd8fc2026-09-21 — fix(lint): recognize Vue slot bindings (#11875)0e7afb30a1c62026-09-21 — chore(deps): update dependency @changesets/cli to v3.0.3 (#11864)