Biome Complete Guide | Fast Linter and Formatter for JavaScript

Why Biome?

The ESLint + Prettier + config files problem:

# Typical setup
.eslintrc.json          ~ 50 lines
.eslintignore
.prettierrc.json        ~ 10 lines
.prettierignore
+ 5-10 ESLint plugins/configs
+ compatibility issues between them
+ slow CI runs

Biome replaces it all:

biome.json              ~ 20 lines

35x faster. One tool. No conflicts.

---

Installation

# npm
npm install --save-dev --save-exact @biomejs/biome

# Initialize config
npx biome init

# Check version
npx biome --version

This creates biome.json.

---

1. Configuration

// biome.json
{
  "$schema": "https://biomejs.dev/schemas/1.9.0/schema.json",
  "organizeImports": {
    "enabled": true
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "correctness": {
        "noUnusedVariables": "error",
        "noUnusedImports": "error"
      },
      "suspicious": {
        "noExplicitAny": "warn",
        "noConsoleLog": "warn"
      },
      "style": {
        "useConst": "error",
        "noVar": "error",
        "useTemplate": "warn"
      },
      "performance": {
        "noDelete": "warn"
      },
      "a11y": {
        "recommended": true
      }
    }
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 100,
    "lineEnding": "lf"
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "trailingCommas": "es5",
      "semicolons": "asNeeded"
    },
    "linter": {
      "enabled": true
    }
  },
  "json": {
    "formatter": {
      "enabled": true,
      "trailingCommas": "none"
    }
  },
  "css": {
    "formatter": {
      "enabled": true
    },
    "linter": {
      "enabled": true
    }
  },
  "files": {
    "ignore": [
      "node_modules",
      "dist",
      ".next",
      ".astro",
      "coverage",
      "*.min.js"
    ]
  }
}

---

2. CLI Commands

# Lint files (check for problems)
npx biome lint .
npx biome lint src/

# Format files (check for formatting issues)
npx biome format .

# Apply format fixes
npx biome format --write .

# Lint + format + organize imports in one command
npx biome check .

# Apply all fixes
npx biome check --write .

# Apply safe fixes only (no potentially breaking changes)
npx biome check --write --unsafe=false .

# CI mode (exit code 1 if issues found)
npx biome ci .

# Format a specific file
npx biome format --write src/index.ts

# Check what would change without writing
npx biome format --write --dry-run .

---

3. Package.json Scripts

{
  "scripts": {
    "lint": "biome lint .",
    "lint:fix": "biome lint --write .",
    "format": "biome format --write .",
    "check": "biome check .",
    "check:fix": "biome check --write .",
    "ci": "biome ci ."
  }
}

---

4. Editor Integration

VS Code

# Install Biome VS Code extension
code --install-extension biomejs.biome

// .vscode/settings.json
{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.organizeImports.biome": "explicit",
    "quickfix.biome": "explicit"
  },
  "[javascript]": { "editor.defaultFormatter": "biomejs.biome" },
  "[typescript]": { "editor.defaultFormatter": "biomejs.biome" },
  "[typescriptreact]": { "editor.defaultFormatter": "biomejs.biome" },
  "[json]": { "editor.defaultFormatter": "biomejs.biome" },
  "[css]": { "editor.defaultFormatter": "biomejs.biome" }
}

JetBrains (WebStorm, IntelliJ)

Settings → Languages & Frameworks → JavaScript → Biome → Enable

---

5. Ignoring Rules

// Disable for next line
// biome-ignore lint/suspicious/noExplicitAny: external API type
const data: any = externalApi.getData()

// Disable for a block
// biome-ignore lint/suspicious/noConsoleLog: debug only
console.log('debugging', value)

// Disable in a file (add at top)
// biome-ignore-file lint/suspicious/noExplicitAny: legacy file

// biome.json — ignore entire directories
{
  "files": {
    "ignore": ["generated/", "vendor/", "*.min.js"]
  },
  "overrides": [
    {
      "include": ["**/*.test.ts"],
      "linter": {
        "rules": {
          "suspicious": {
            "noExplicitAny": "off"
          }
        }
      }
    }
  ]
}

---

6. Migrating from ESLint + Prettier

# Automated migration (reads your existing config)
npx @biomejs/biome migrate eslint --write
npx @biomejs/biome migrate prettier --write

# Manual migration checklist:
# 1. Install Biome
# 2. Run: npx biome init
# 3. Copy settings from .eslintrc + .prettierrc to biome.json
# 4. Run: npx biome check --write .
# 5. Fix any remaining issues
# 6. Remove ESLint + Prettier configs and packages
# 7. Update scripts in package.json
# 8. Update CI pipeline

# Remove ESLint + Prettier
npm uninstall eslint eslint-config-airbnb prettier @typescript-eslint/eslint-plugin
# (and all other eslint-* packages)

# Remove config files
rm .eslintrc.json .eslintignore .prettierrc.json .prettierignore

---

7. Git Hooks Integration

# .husky/pre-commit
npx biome check --write --staged
# or check only (no auto-fix)
npx biome ci --changed --since=HEAD

With lint-staged:

// package.json
{
  "lint-staged": {
    "*.{js,ts,jsx,tsx,json,css}": [
      "biome check --write --no-errors-on-unmatched --files-ignore-unknown=true"
    ]
  }
}

---

8. CI Integration

# .github/workflows/ci.yml
- name: Run Biome
  run: npx biome ci .

# Or with explicit install
- name: Install dependencies
  run: npm ci

- name: Lint and format check
  run: npx biome ci --reporter=github .
  # --reporter=github adds inline annotations to PR review

---

Biome vs ESLint vs Prettier

	Biome	ESLint + Prettier
Speed	35x faster	Baseline
Config	1 file	2-4 files
TypeScript	Built-in	Via plugin
Plugins	Growing	Huge ecosystem
Rules	270+	1000+ (with plugins)
JSX	Yes	Via plugin
CSS	Yes	Via plugin
JSON	Yes	Via plugin
Formatting	Built-in	Prettier
Import sorting	Built-in	Via plugin

---

Supported Languages

Language	Lint	Format
JavaScript	✅	✅
TypeScript	✅	✅
JSX/TSX	✅	✅
JSON/JSONC	✅	✅
CSS	✅	✅
GraphQL	✅	✅
HTML	🚧 (coming)	🚧
Markdown	❌	❌

---

Key Takeaways

• One tool replaces ESLint + Prettier + import sorter — zero conflicts
• 35x faster than ESLint — CI runs go from 30s to under 1s
• biome check --write = lint + format + organize imports in one command
• biome ci for CI pipelines — non-zero exit code on any issue
• Migration: npx biome migrate eslint auto-converts your ESLint config
• VS Code: install the Biome extension + formatOnSave for seamless DX