biome.json Configuration Reference

Frequently Asked Questions

What is biome.json and what does it configure?

biome.json is the single configuration file for Biome — a fast, Rust-based toolchain that replaces both Prettier (formatter) and ESLint (linter) with one tool and one config. The file lives at the project root and controls four top-level systems: "formatter" (indentation, line width, quote style, trailing commas), "linter" (400+ rules across accessibility, complexity, correctness, performance, security, and style), "organizeImports" (automatic import sorting), and "vcs" (Git integration for staged-file workflows). Optional "files" and "overrides" sections handle inclusion/exclusion and per-glob rule overrides. When biome.json is absent, Biome falls back to built-in defaults, so no config is required to start — but the file unlocks project-specific tuning and is committed to version control so every contributor and CI run uses identical settings.

How do I migrate from Prettier to Biome formatter?

Biome ships a migration command: run `npx @biomejs/biome migrate prettier --write` at the project root. It reads .prettierrc / .prettierrc.json / prettier.config.js and converts the recognized options to biome.json equivalents — printWidth becomes "lineWidth", tabWidth becomes "indentWidth", singleQuote sets "quoteStyle", and so on. Options Biome does not support (htmlWhitespaceSensitivity, embeddedLanguageFormatting) are silently dropped. After migration, delete .prettierrc and remove the prettier package. A few formatting differences survive migration because Biome deliberately diverges from Prettier in certain edge cases (template-literal indentation, long ternary chains). Run `biome format --write .` and review the diff; most projects see zero or near-zero changes beyond the expected rule differences.

How do I migrate from ESLint to Biome linter?

Run `npx @biomejs/biome migrate eslint --write`. It reads .eslintrc* / eslint.config.js and maps rules it knows to biome.json linter rules under the appropriate group (correctness, suspicious, style, etc.). Rules ESLint has that Biome has not implemented are listed in the migration output so you can track coverage gaps. The most common gap: ESLint plugins for React hooks, testing-library, or import resolution have no Biome equivalent yet. The migration command also rewrites extends like "eslint:recommended" and "plugin:@typescript-eslint/recommended" to the Biome equivalents. After migration, remove eslint, @eslint/js, and any plugin packages. If you need both tools during a transition period, set "linter.enabled": false in biome.json and run ESLint separately, or vice versa.

What does the "overrides" section do in biome.json?

The "overrides" array lets you apply different formatter or linter settings to specific file globs. Each entry has a "include" array of glob patterns plus any subset of the top-level formatter/linter/organizeImports keys. Override entries are applied in order; later entries win. Common uses: disable formatting for generated files ("include": ["**/generated/**"], "formatter": {"enabled": false}); relax naming rules for test files ("include": ["**/*.test.ts"], "linter": {"rules": {"style": {"useNamingConvention": "off"}}}); apply different indent size to YAML ("include": ["**/*.yml"], "formatter": {"indentWidth": 2}). Glob syntax follows gitignore patterns. The "files.ignore" array handles global exclusion without a formatter/linter toggle — use it for node_modules, dist, and build artifacts.

How do I enable Biome in VS Code?

Install the "Biome" extension (biomejs.biome) from the VS Code Marketplace. Then configure VS Code to use Biome as the default formatter: open settings.json and add "[javascript]": {"editor.defaultFormatter": "biomejs.biome"}, "[typescript]": {"editor.defaultFormatter": "biomejs.biome"}, "[json]": {"editor.defaultFormatter": "biomejs.biome"}, and "editor.formatOnSave": true. For lint-on-save, add "editor.codeActionsOnSave": {"source.fixAll.biome": "explicit"}. The extension reads biome.json from the workspace root. If you have a monorepo with multiple biome.json files, the extension uses the closest parent biome.json relative to the open file. You can also set "biome.lspBin" in settings to point to a local binary if you want to pin a specific Biome version independently of the project's npm install.

How do I run Biome in CI?

The canonical CI command is `npx @biomejs/biome ci .` — it runs format checking, lint, and import organization in a single pass and exits non-zero on any violation. It does not write files, so it is safe in read-only CI environments. To check only formatting: `biome format .` (exits non-zero on diff). To check only lint: `biome lint .`. For staged-file workflows (pre-commit hooks), enable VCS integration in biome.json: "vcs": {"enabled": true, "clientKind": "git", "useIgnoreFile": true, "defaultBranch": "main"} and run `biome check --changed --since=main`. This tells Biome to only process files changed since the branch diverged from main, making pre-commit hooks fast even in large repos. Pair with lint-staged or Husky for automatic pre-commit enforcement.

Can Biome format JSON and JSONC files?

Yes. Biome formats JSON files by default when you run `biome format` or `biome check`. JSONC (JSON with Comments) requires "json": {"parser": {"allowComments": true}} in the biome.json formatter section. You can also allow trailing commas with "allowTrailingCommas": true — useful for tsconfig.json, .vscode/settings.json, and similar files that use the relaxed JSONC format. The JSON formatter respects the top-level "formatter" settings (indentWidth, lineWidth, indentStyle) but JSON-specific overrides live under the "json.formatter" key. One common override: format JSON with 2-space indent even when TypeScript uses tabs — add an "overrides" entry targeting "**/*.json" with "formatter": {"indentWidth": 2, "indentStyle": "space"}.

What is the "$schema" key in biome.json?

The "$schema" key points to the JSON Schema that describes all valid biome.json options. Biome publishes versioned schemas at https://biomejs.dev/schemas/<version>/schema.json — for example, "https://biomejs.dev/schemas/1.9.4/schema.json". When this key is present, editors that understand JSON Schema (VS Code with the JSON Language Features extension, JetBrains IDEs, Neovim with coc-json) provide autocomplete for all keys and values, inline documentation, and validation errors for typos or unsupported options. This is similar to the "$schema" key in tsconfig.json, .vscode/settings.json, or .github/workflows YAML. Always include it: it costs nothing, and it turns the config file into self-documenting, IDE-aware JSON.