@gfmio/config-biome

Shared Biome configuration for linting, formatting, and code quality across JavaScript, TypeScript, JSON, CSS, HTML, and GraphQL projects.

Installation

npm install --save-dev @gfmio/config-biome @biomejs/biome

yarn add --dev @gfmio/config-biome @biomejs/biome

pnpm add --save-dev @gfmio/config-biome @biomejs/biome

bun add --dev @gfmio/config-biome @biomejs/biome

Usage

Create a biome.json file in your project root:

{
  "$schema": "https://biomejs.dev/schemas/2.3.2/schema.json",
  "extends": ["@gfmio/config-biome/biome.json"],
  "root": true,
}

That's it! The shared configuration will be applied to your project.

Extending the Configuration

You can override or extend any settings from the shared config:

{
  "$schema": "https://biomejs.dev/schemas/2.3.2/schema.json",
  "extends": ["@gfmio/config-biome/biome.json"],
  "root": true,
  "formatter": {
    "lineWidth": 100
  },
  "linter": {
    "rules": {
      "suspicious": {
        "noConsole": "error"
      }
    }
  }
}

Configuration Highlights

This configuration provides opinionated defaults designed to catch bugs, enforce best practices, and maintain code quality while remaining flexible enough for various project types.

Formatter Settings

• Line width: 120 characters
• Indentation: 2 spaces
• Line endings: LF (Unix-style)
• JavaScript/TypeScript:
  • Single quotes for strings
  • Double quotes for JSX attributes
  • Always use semicolons
  • Always use arrow function parentheses
  • Trailing commas everywhere (ES5+)
• EditorConfig: Respects .editorconfig files when present

Linter Rules

Strict enforcement for:

• Correctness issues (undefined variables, unreachable code, etc.)
• Security vulnerabilities (eval, dangerouslySetInnerHTML)
• Common bugs (duplicate keys, self-assignment, etc.)
• Performance anti-patterns (accumulating spreads, unnecessary delete)

Warnings for:

• Explicit any types (helps migration to strict typing)
• Non-null assertions (potential runtime issues)
• All console statements (including console.log)
• Barrel files and re-export-all patterns (performance)

Flexible on:

• Default exports (project-dependent preference)
• forEach usage (common pattern despite performance considerations)
• Literal object keys (allows computed properties when needed)

Language Support

• JavaScript/TypeScript: Full support with modern syntax
• JSON: Allows comments and trailing commas (JSONC-style)
• CSS: Supports CSS Modules and Tailwind directives
• HTML: Experimental full support for Vue/Svelte/Astro components
• GraphQL: Formatting and linting enabled
• Grit: Code transformation language support

Smart Overrides

Context-aware rules for different file types:

• Test files (**/*.test.ts, **/*.spec.ts, tests/**/*):

  • Allows explicit any for test fixtures
  • Allows empty blocks for stub implementations
  • Relaxed async/await requirements

• Config files (**/*.config.{ts,js,mjs,cjs}):

  • Allows default exports (common convention)

• Type definitions (**/*.d.ts):

  • Disables unused variable checks

• Scripts and CLI (scripts/**/*, cli/**/*, bin/**/*):

  • Allows console statements

• TSConfig/JSConfig files:

  • Allows comments and trailing commas

VCS Integration

• Git integration enabled by default
• Respects .gitignore patterns
• Supports --changed and --since CLI flags for incremental checking

Excluded Directories

The following directories are force-ignored (completely excluded from all operations):

• node_modules
• dist, build, out
• .next (Next.js)
• coverage (test coverage reports)
• .turbo (Turborepo cache)
• Minified files (*.min.js, *.min.css)

Common Commands

# Check all files (lint + format)
npx @biomejs/biome check .

# Check and auto-fix issues
npx @biomejs/biome check --write .

# Format only
npx @biomejs/biome format --write .

# Lint only
npx @biomejs/biome lint --write .

# Check only changed files (requires git)
npx @biomejs/biome check --changed

# CI mode (fails on warnings)
npx @biomejs/biome ci .

Package Scripts

Add these to your package.json:

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

Editor Integration

VS Code

Install the official Biome VS Code extension:

code --install-extension biomejs.biome

Add to your .vscode/settings.json:

{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "quickfix.biome": "explicit",
    "source.organizeImports.biome": "explicit"
  }
}

Other Editors

Biome has plugins for:

• JetBrains IDEs (WebStorm, IntelliJ, etc.)
• Neovim
• Sublime Text
• Zed (built-in support)

CI/CD Integration

GitHub Actions

name: Lint

on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v1
      - run: bun install
      - run: bun run biome ci .

Pre-commit Hook

Using husky and lint-staged:

{
  "devDependencies": {
    "husky": "^9.0.0",
    "lint-staged": "^15.0.0"
  },
  "lint-staged": {
    "*": "biome check --write --no-errors-on-unmatched"
  }
}

npx husky init
echo "npx lint-staged" > .husky/pre-commit

Migration from ESLint/Prettier

Biome can coexist with ESLint/Prettier during migration:

1. Install this config alongside existing tools
2. Run biome check --write . to see what changes Biome makes
3. Gradually migrate rules and remove ESLint/Prettier config
4. Remove old dependencies when ready

See the Biome migration guide for detailed instructions.

Philosophy

This configuration follows these principles:

1. Prevent bugs: Strict on correctness and suspicious code patterns
2. Encourage best practices: Error on performance and security issues
3. Allow flexibility: Warn or disable opinionated style rules
4. Support common patterns: Smart overrides for tests, configs, scripts
5. Reduce friction: Sensible defaults that work for most projects
6. Stay maintainable: Clear structure and documented decisions

Requirements

• Biome ^2.3.0 or later
• Node.js 16+ or Bun

License

MIT

Author

Frédérique Mittelstaedt ([email protected])

Contributing

Issues and pull requests are welcome! This is a personal configuration, but suggestions for improvements are appreciated.

Resources

• Biome Documentation
• Biome Linter Rules
• Biome Formatter
• Biome Blog