Biomev2.5INTERMEDIATE

Biome

Fast formatter, linter, and code-assist toolchain for JavaScript, TypeScript, JSON, CSS, GraphQL, and modern web projects.

14 min read

biomeformatterlinterjavascripttypescripteslintprettiercode-quality

Loading your progress

Installation & Setup

Install a pinned Biome release and create the project configuration.

Install & Pin Biome

Install the native Biome CLI as an exact development dependency.

bash

npm i -D -E @biomejs/biome
npx @biomejs/biome version

📌 Pin the exact version so local, editor, and CI results match

⚡ Biome ships native binaries for supported platforms

💡 Use your package manager to invoke the local binary

🔍 The package manager selects the correct platform package

installnpmpnpmyarnbun

Initialize Configuration

Generate biome.json, then enable the shared project defaults.

json

{
  "$schema": "https://biomejs.dev/schemas/2.5.6/schema.json",
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100
  },
  "linter": {
    "enabled": true,
    "rules": {
      "preset": "recommended"
    }
  }
}

🟢 Run npx @biomejs/biome init to generate the first config

📌 Keep the schema URL aligned with the installed CLI version

💡 biome.jsonc is available when configuration comments help

🔍 Most options work without extra plugins or dependencies

initconfigurationschema

Core Commands

Run formatting, linting, and Assist checks from one CLI.

Check, Format & Lint

Choose the combined command or run each tool independently.

bash

# Format, lint, and run Assist checks
npx @biomejs/biome check .

# Run one tool only
npx @biomejs/biome format .
npx @biomejs/biome lint .

🟢 check is the normal all-in-one local quality command

📌 Commands report changes unless --write is provided

💡 Pass paths to keep focused checks fast

🔍 explain accepts a rule or diagnostic name

checkformatlintcli

Write, Unsafe Fixes & Scopes

Apply fixes deliberately and limit work to relevant Git changes.

bash

# Apply formatting and safe fixes
npx @biomejs/biome check --write .

# Include fixes that may change behavior
npx @biomejs/biome check --write --unsafe .

📌 Review unsafe fixes because they can change runtime behavior

⚡ --staged is useful in a pre-commit hook

💡 --changed keeps branch checks focused

🔍 --since overrides vcs.defaultBranch for one run

writeunsafestagedchanged

Formatter

Configure consistent formatting globally and per language.

Project Formatting Options

Set indentation, line width, line endings, and EditorConfig behavior.

json

{
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100,
    "lineEnding": "lf"
  }
}

📌 Space indentation uses indentWidth; tabs ignore it

💡 useEditorconfig imports supported .editorconfig settings

🔍 formatWithErrors defaults to false

⚡ lineEnding auto follows the current operating system

formattereditorconfigindentation

Language-Specific Formatting

Override JavaScript, JSON, and CSS formatting or parser options.

json

{
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "semicolons": "asNeeded",
      "trailingCommas": "all"
    }
  },
  "json": {
    "formatter": {
      "trailingCommas": "none"
    }
  }
}

💡 Language options override shared formatter settings

📌 Enable Tailwind directives for Tailwind CSS syntax

🔍 JSONC gets comment and trailing-comma parser defaults

⚡ Keep project conventions explicit for predictable diffs

javascriptjsoncsstailwind

Linter Rules

Choose a stable rule preset and tune rule severity.

Presets, Groups & Severity

Start from a preset, then adjust groups and individual rules.

json

{
  "linter": {
    "enabled": true,
    "rules": {
      "preset": "recommended",
      "suspicious": {
        "noExplicitAny": "warn"
      },
      "style": {
        "useConst": "error"
      }
    }
  }
}

🟢 recommended is the default stable starting preset

📌 Nursery rules can change outside major releases

💡 Severity can be info, warn, error, on, or off

🔍 Individual rule settings override their group

linterrulespresetseverity

Framework & Project Domains

Enable rules that understand frameworks, tests, and project structure.

json

{
  "linter": {
    "domains": {
      "react": "recommended",
      "test": "recommended",
      "project": "recommended"
    }
  }
}

💡 Domains add rules for detected tools and frameworks

📌 Project rules scan dependencies and add some overhead

🔍 Domain values are recommended, all, or none

⚡ Use --only or --skip for temporary CLI selection

domainsreactnextjsproject

Assist Actions

Configure safe source transformations alongside linting and formatting.

Organize Imports

Sort, merge, and group imports with the recommended source action.

json

{
  "assist": {
    "enabled": true,
    "actions": {
      "source": {
        "organizeImports": "on"
      }
    }
  }
}

⚡ check --write applies enabled Assist actions

💡 Groups define import blocks from top to bottom

📌 Side-effect imports are not sorted by default

🔍 The action also merges imports from the same source

assistimportsorganize-imports

Additional Source Actions

Enable opt-in sorting actions for common JavaScript structures.

json

{
  "assist": {
    "actions": {
      "source": {
        "useSortedAttributes": "on",
        "useSortedEnumMembers": "on",
        "useSortedInterfaceMembers": "on",
        "useSortedKeys": "on"
      }
    }
  }
}

💡 Enable only ordering rules your team wants enforced

📌 Sorting object keys may create large intentional diffs

🔍 assist.includes narrows actions after files.includes

⚡ A specific action overrides the source recommendation

assistsortingsource-actions

Files & Version Control

Control the project file set and integrate checks with Git.

Includes, Exclusions & Generated Files

Use ordered glob patterns to define what Biome processes or scans.

json

{
  "files": {
    "includes": [
      "src/**",
      "tests/**",
      "!**/*.generated.ts",
      "!!**/dist",
      "!!**/coverage"
    ],
    "ignoreUnknown": true
  }
}

📌 Patterns are evaluated in order, so later entries can restore files

⚡ Use !! for build output the scanner must never index

💡 Use a single ! when generated types still aid analysis

🔍 node_modules is ignored without an explicit pattern

filesglobsignoregenerated

Git Integration & Changed Files

Read Git ignore files and define the comparison branch for focused checks.

json

{
  "vcs": {
    "enabled": true,
    "clientKind": "git",
    "useIgnoreFile": true,
    "defaultBranch": "main"
  }
}

💡 Git integration reads .gitignore and .git/info/exclude

⚡ Use check --staged locally and ci --changed in CI

📌 vcs.root is relative to the Biome configuration file

🔍 --since can replace defaultBranch for one command

gitvcschangedgitignore

Suppressions

Document narrow exceptions without weakening a rule globally.

Inline, File & Range Suppressions

Suppress a diagnostic for one line, one file, or a bounded range.

javascript

// Suppress the next line
// biome-ignore lint/suspicious/noDebugger: browser debugging session
debugger;

📌 Always include the reason after the diagnostic category

💡 Prefer one-rule suppressions over disabling a whole group

🔍 Range suppressions require a matching end comment

⚠️ Unused or misplaced suppressions produce diagnostics

suppressionsignorediagnostics

Overrides & Language Support

Apply targeted settings and opt into experimental language support carefully.

Per-File Overrides

Change formatter and linter behavior for tests, generated code, or scripts.

json

{
  "overrides": [
    {
      "includes": ["**/*.test.ts", "**/*.spec.ts"],
      "linter": {
        "domains": {
          "test": "recommended"
        },
        "rules": {
          "suspicious": {
            "noExplicitAny": "off"
          }
        }
      }
    }
  ]
}

💡 Overrides are applied to files matched by files.includes

📌 Keep exceptions narrow and tied to a real file pattern

🔍 Later matching overrides can refine earlier settings

⚡ Domains can be activated only where their files live

overridestestsgenerated-files

Supported & Experimental Languages

Know which file types are stable and which require explicit opt-in.

json

{
  "html": {
    "experimentalFullSupportEnabled": true
  }
}

🟢 JS, TS, JSX, TSX, JSON, CSS, and GraphQL are supported

📌 Vue, Svelte, and Astro support remains experimental

💡 Embedded CSS and GraphQL template parsing is opt-in

🔍 Check language support before replacing specialized tools

languageshtmlvuesvelteastro

Editor Integration

Use the official VS Code extension for formatting and fixes on save.

VS Code Setup & Save Actions

Select Biome as the formatter and apply safe actions explicitly on save.

json

{
  "[javascript][typescript][javascriptreact][typescriptreact]": {
    "editor.defaultFormatter": "biomejs.biome",
    "editor.formatOnSave": true
  },
  "editor.codeActionsOnSave": {
    "source.fixAll.biome": "explicit",
    "source.organizeImports.biome": "explicit"
  }
}

🟢 Install the official Biome extension from the marketplace

📌 Use explicit actions to avoid unwanted workspace edits

💡 requireConfiguration prevents Biome in unrelated folders

🔍 Multi-root workspaces get one Biome instance per root

vscodeeditorformat-on-savelsp

Migration

Convert existing ESLint and Prettier configuration into Biome.

Migrate from ESLint

Translate supported ESLint settings, plugins, ignores, and rules.

bash

# Preview the migration
npx @biomejs/biome migrate eslint

# Write the converted configuration
npx @biomejs/biome migrate eslint --write

📌 Review the generated rule mapping before removing ESLint

💡 Legacy and flat JavaScript configs are supported

🔍 YAML ESLint configuration is not migrated

⚠️ Plugin behavior may not have an exact Biome equivalent

migrationeslintrules

Migrate from Prettier

Convert supported Prettier options and ignore patterns.

bash

# Preview the migration
npx @biomejs/biome migrate prettier

# Write the converted configuration
npx @biomejs/biome migrate prettier --write

📌 Biome and Prettier have different formatter defaults

💡 The migration reads Prettier config and ignore files

🔍 JSON5, TOML, and YAML configs are not migrated

⚠️ Compare the first formatting diff before removing Prettier

migrationprettierformatter

Monorepos

Share root settings while allowing package-specific configuration.

Root & Nested Configurations

Extend the root config from packages with the Biome v2 microsyntax.

json

{
  "$schema": "https://biomejs.dev/schemas/2.5.6/schema.json",
  "linter": {
    "rules": {
      "preset": "recommended"
    }
  },
  "formatter": {
    "lineWidth": 100
  }
}

🟢 Place the first config at the monorepo root

💡 extends // inherits the discovered root configuration

📌 Nested independent configs must set root to false

🔍 Run Biome from the root or an individual package

monorepoworkspacesextends

Continuous Integration

Run non-writing checks locally and in hosted CI systems.

Use biome ci

Run CI-focused checks with annotations and no write option.

bash

# Check the complete repository
npx @biomejs/biome ci .

# Fail when warnings are present
npx @biomejs/biome ci --error-on-warnings .

📌 ci never writes files or applies fixes

⚡ GitHub environments receive native annotations

💡 Limit threads when the runner has constrained resources

🔍 Reporters include JSON, JUnit, SARIF, and GitLab

cireportersgithub-actions

GitHub Actions

Install a pinned Biome binary with the first-party setup action.

yaml

name: Code quality

on:
  pull_request:
  push:

jobs:
  biome:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v5
      - uses: biomejs/setup-biome@v2
        with:
          version: 2.5.6
      - run: biome ci .

📌 Pin the CLI version instead of using latest

💡 The setup action avoids a Node.js install for basic CI

🔍 Fetch history before comparing with the base branch

⚡ Install dependencies first when config extends a package

github-actionscisetup-biome

Troubleshooting

Inspect configuration, diagnostics, daemon state, and slow project scans.

Diagnostics & Performance

Use built-in reports and tracing before changing project rules.

bash

# Show version and platform information
npx @biomejs/biome version

# Print a debugging report
npx @biomejs/biome rage

# Explain a diagnostic or daemon topic
npx @biomejs/biome explain noDebugger
npx @biomejs/biome explain daemon-logs

🟢 Start by confirming the CLI and config versions match

⚡ Force-ignore dist and build folders before deeper tracing

📌 Project-domain rules intentionally add scanner work

🔍 rage output is designed for debugging issue reports

troubleshootingperformanceragetracing

Biome

Table of Contents

Installation & Setup

Core Commands

Formatter

Linter Rules

Assist Actions

Files & Version Control

Suppressions

Overrides & Language Support

Editor Integration

Migration

Monorepos

Continuous Integration

Troubleshooting