Biome Configuration Skill

Biome Configuration

Master Biome configuration including biome.json setup, schema versions, VCS integration, and project organization for optimal JavaScript/TypeScript tooling.

Overview

Biome is a fast, modern toolchain for JavaScript and TypeScript projects that combines linting and formatting in a single tool. It's designed as a performant alternative to ESLint and Prettier, written in Rust for maximum speed.

Installation and Setup

Basic Installation

Install Biome in your project:

npm install --save-dev @biomejs/biome
# or
pnpm add -D @biomejs/biome
# or
yarn add -D @biomejs/biome

Initialize Configuration

Create a basic biome.json configuration:

npx biome init

This creates a biome.json file in your project root.

Configuration File Structure

Basic biome.json

{
  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
  "vcs": {
    "enabled": true,
    "clientKind": "git",
    "useIgnoreFile": true
  },
  "files": {
    "ignoreUnknown": false,
    "ignore": []
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 80
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true
    }
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "trailingCommas": "es5"
    }
  }
}

Schema Versioning

Always use the correct schema version matching your Biome installation:

# Check Biome version
npx biome --version

# Migrate configuration to current version
npx biome migrate --write

The $schema field enables IDE autocomplete and validation:

{
  "$schema": "https://biomejs.dev/schemas/2.3.6/schema.json"
}

VCS Integration

Configure version control integration to respect .gitignore:

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

Options:

enabled: Enable VCS integration
clientKind: "git" for Git repositories
useIgnoreFile: Respect .gitignore patterns
defaultBranch: Default branch name for operations

File Management

File Patterns

Control which files Biome processes:

{
  "files": {
    "ignoreUnknown": false,
    "ignore": [
      "**/node_modules/**",
      "**/dist/**",
      "**/.next/**",
      "**/build/**",
      "**/.cache/**"
    ],
    "include": ["src/**/*.ts", "src/**/*.tsx"]
  }
}

Common Ignore Patterns

{
  "files": {
    "ignore": [
      "**/node_modules/",
      "**/dist/",
      "**/build/",
      "**/.next/",
      "**/.cache/",
      "**/coverage/",
      "**/*.min.js",
      "**/*.log"
    ]
  }
}

Formatter Configuration

Basic Formatter Settings

{
  "formatter": {
    "enabled": true,
    "formatWithErrors": false,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineEnding": "lf",
    "lineWidth": 80
  }
}

Options:

enabled: Enable/disable formatter
formatWithErrors: Format even with syntax errors
indentStyle: "space" or "tab"
indentWidth: Number of spaces (2 or 4 recommended)
lineEnding: "lf", "crlf", or "cr"
lineWidth: Maximum line length

Language-Specific Formatting

JavaScript/TypeScript

{
  "javascript": {
    "formatter": {
      "quoteStyle": "single",
      "quoteProperties": "asNeeded",
      "trailingCommas": "all",
      "semicolons": "always",
      "arrowParentheses": "always",
      "bracketSpacing": true,
      "bracketSameLine": false
    }
  }
}

JSON

{
  "json": {
    "formatter": {
      "enabled": true,
      "indentStyle": "space",
      "indentWidth": 2,
      "lineWidth": 80,
      "trailingCommas": "none"
    }
  }
}

Linter Configuration

Enable Recommended Rules

{
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true
    }
  }
}

Rule Categories

Configure specific rule groups:

{
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "a11y": {
        "recommended": true
      },
      "complexity": {
        "recommended": true
      },
      "correctness": {
        "recommended": true
      },
      "performance": {
        "recommended": true
      },
      "security": {
        "recommended": true
      },
      "style": {
        "recommended": true
      },
      "suspicious": {
        "recommended": true
      }
    }
  }
}

Fine-Grained Rule Control

Enable or disable specific rules:

{
  "linter": {
    "rules": {
      "recommended": true,
      "suspicious": {
        "noExplicitAny": "error",
        "noConsoleLog": "warn"
      },
      "style": {
        "useConst": "error",
        "noVar": "error"
      }
    }
  }
}

Rule levels:

"off": Disable rule
"warn": Show warning
"error": Fail check

Monorepo Configuration

Root Configuration

{
  "$schema": "https://biomejs.dev/schemas/2.3.6/schema.json",
  "extends": [],
  "files": {
    "ignore": ["**/node_modules/", "**/dist/"]
  },
  "formatter": {
    "enabled": true,
    "indentWidth": 2
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true
    }
  }
}

Package-Specific Overrides

Each package can have its own biome.json:

{
  "$schema": "https://biomejs.dev/schemas/2.3.6/schema.json",
  "extends": ["../../biome.json"],
  "linter": {
    "rules": {
      "suspicious": {
        "noConsoleLog": "off"
      }
    }
  }
}

Best Practices

Use Schema URLs - Always include $schema for IDE support
Version Management - Run biome migrate after updates
VCS Integration - Enable VCS to respect .gitignore
Consistent Formatting - Set clear formatter rules across team
Rule Documentation - Document why specific rules are disabled
Monorepo Strategy - Use extends for shared configuration
CI Integration - Run biome ci in continuous integration
Pre-commit Hooks - Validate code before commits
Editor Integration - Install Biome VSCode/IDE extensions
Regular Updates - Keep Biome updated for new features

Common Pitfalls

Schema Mismatch - Using outdated schema version
Missing Migration - Not running migrate after updates
Overly Strict - Enabling all rules without team agreement
No VCS Integration - Not respecting gitignore patterns
Inconsistent Config - Different settings across packages
Ignored Warnings - Dismissing warnings that indicate issues
No Editor Setup - Missing IDE integration for real-time feedback
Large Line Width - Setting lineWidth too high reduces readability
Mixed Quotes - Not enforcing consistent quote style
No CI Enforcement - Not running checks in CI pipeline

Advanced Topics

Overrides Per Path

{
  "overrides": [
    {
      "include": ["scripts/**/*.js"],
      "linter": {
        "rules": {
          "suspicious": {
            "noConsoleLog": "off"
          }
        }
      }
    },
    {
      "include": ["**/*.test.ts"],
      "linter": {
        "rules": {
          "suspicious": {
            "noExplicitAny": "off"
          }
        }
      }
    }
  ]
}

Custom Scripts

Add to package.json:

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

CI/CD Integration

# CI mode (fails on warnings)
biome ci .

# Check without fixing
biome check .

# Fix automatically
biome check --write .

# Format only
biome format --write .

When to Use This Skill

Setting up Biome in new projects
Migrating from ESLint/Prettier to Biome
Configuring Biome for monorepos
Customizing linting and formatting rules
Troubleshooting Biome configuration issues
Integrating Biome with CI/CD pipelines
Establishing team code standards
Optimizing Biome performance

Troubleshooting

Schema Version Mismatch

# Error: Schema version doesn't match CLI version
npx biome migrate --write

Files Not Being Checked

Check:

VCS integration and .gitignore
files.ignore patterns
files.include if specified
File extensions supported by Biome

Rules Not Applying

Verify:

linter.enabled is true
Rule category is enabled
Rule name is correct
No overrides disabling the rule

Performance Issues

Optimize:

Use files.ignore for large directories
Enable VCS integration
Exclude generated files
Update to latest Biome version

Agent Skills: Biome Configuration

Install this agent skill to your local

Skill Files