biome.json: The Biome Configuration File
biome.json is the single configuration file that drives Biome formatter, linter, import sorting, file selection, and VCS behavior.
One config file controls everything. Adding a $schema gives editor autocomplete and lets you catch typos before they reach CI.
What it does
biome.json (or biome.jsonc for comments) configures Biome. Top-level sections include formatter, linter, javascript/json/css for language settings, files for selection, vcs for git integration, and assist for actions like import sorting. Biome reads the nearest config and merges nested ones in v2.
Common usage
{
"$schema": "https://biomejs.dev/schemas/2.0.0/schema.json",
"vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true },
"files": { "ignoreUnknown": true },
"formatter": { "enabled": true, "indentStyle": "space", "indentWidth": 2 },
"linter": { "enabled": true, "rules": { "recommended": true } }
}Options
| Key | What it does |
|---|---|
| $schema | JSON schema URL for the pinned version (enables autocomplete) |
| formatter | Global formatter settings (indentStyle, indentWidth, lineWidth) |
| linter.rules | Rule groups and severities; recommended:true is the baseline |
| files | Include/ignore globs and ignoreUnknown |
| vcs | Git integration: enabled, clientKind, useIgnoreFile, defaultBranch |
| assist | Assist actions such as organize imports (v2) |
Common errors in CI
A mistyped key produces "Found an unknown key" and Biome exits 1 before processing files. A $schema URL whose version does not match the installed binary can flag valid keys as unknown; keep the schema version and the pinned package version aligned. Use biome.jsonc if you need comments, since plain biome.json rejects them.