Biome Linting

Expert knowledge of Biome's linting capabilities, rule categories, and code quality enforcement for JavaScript and TypeScript projects.

Overview

Biome's linter provides fast, comprehensive code quality checks with a focus on correctness, performance, security, and best practices. It's designed to catch common bugs and enforce consistent code patterns.

Core Commands

Basic Linting

bash

# Check files without fixing
biome check .

# Check and auto-fix
biome check --write .

# Check specific files
biome check src/**/*.ts

# CI mode (strict, fails on warnings)
biome ci .

Command Options

bash

# Verbose output
biome check --verbose .

# JSON output
biome check --json .

# Only lint (skip formatting)
biome lint .

# Apply safe fixes only
biome check --write --unsafe=false .

Rule Categories

Accessibility (a11y)

Rules for web accessibility and WCAG compliance:

json

{
  "linter": {
    "rules": {
      "a11y": {
        "recommended": true,
        "noAccessKey": "error",
        "noAriaHiddenOnFocusable": "error",
        "noAutofocus": "warn",
        "noBlankTarget": "error",
        "noPositiveTabindex": "error",
        "useAltText": "error",
        "useAnchorContent": "error",
        "useButtonType": "error",
        "useValidAriaProps": "error"
      }
    }
  }
}

Common violations:

Missing alt text on images
Autofocus on form elements
Positive tabindex values
Links without content
Invalid ARIA properties

Complexity

Rules to reduce code complexity:

json

{
  "linter": {
    "rules": {
      "complexity": {
        "recommended": true,
        "noBannedTypes": "error",
        "noExcessiveCognitiveComplexity": "warn",
        "noExtraBooleanCast": "error",
        "noMultipleSpacesInRegularExpressionLiterals": "error",
        "noUselessCatch": "error",
        "noUselessConstructor": "error",
        "noUselessEmptyExport": "error",
        "noUselessFragments": "error",
        "noUselessLabel": "error",
        "noUselessRename": "error",
        "noUselessSwitchCase": "error",
        "noWith": "error"
      }
    }
  }
}

Correctness

Rules for code correctness and bug prevention:

json

{
  "linter": {
    "rules": {
      "correctness": {
        "recommended": true,
        "noChildrenProp": "error",
        "noConstAssign": "error",
        "noConstantCondition": "error",
        "noConstructorReturn": "error",
        "noEmptyPattern": "error",
        "noGlobalObjectCalls": "error",
        "noInnerDeclarations": "error",
        "noInvalidConstructorSuper": "error",
        "noNewSymbol": "error",
        "noNonoctalDecimalEscape": "error",
        "noPrecisionLoss": "error",
        "noSelfAssign": "error",
        "noSetterReturn": "error",
        "noSwitchDeclarations": "error",
        "noUndeclaredVariables": "error",
        "noUnreachable": "error",
        "noUnreachableSuper": "error",
        "noUnsafeFinally": "error",
        "noUnsafeOptionalChaining": "error",
        "noUnusedLabels": "error",
        "noUnusedVariables": "error",
        "useIsNan": "error",
        "useValidForDirection": "error",
        "useYield": "error"
      }
    }
  }
}

Critical rules:

```
noUndeclaredVariables
```
: Catch undeclared variables
```
noUnusedVariables
```
: Remove unused code
```
noConstAssign
```
: Prevent const reassignment
```
noUnreachable
```
: Detect unreachable code
```
useIsNan
```
: Use isNaN() for NaN checks

Performance

Rules for performance optimization:

json

{
  "linter": {
    "rules": {
      "performance": {
        "recommended": true,
        "noAccumulatingSpread": "warn",
        "noDelete": "error"
      }
    }
  }
}

Security

Rules for security best practices:

json

{
  "linter": {
    "rules": {
      "security": {
        "recommended": true,
        "noDangerouslySetInnerHtml": "error",
        "noDangerouslySetInnerHtmlWithChildren": "error",
        "noGlobalEval": "error"
      }
    }
  }
}

Critical security rules:

Prevent XSS via innerHTML
Block eval() usage
Detect security vulnerabilities

Style

Code style and consistency rules:

json

{
  "linter": {
    "rules": {
      "style": {
        "recommended": true,
        "noArguments": "error",
        "noCommaOperator": "error",
        "noImplicitBoolean": "warn",
        "noNegationElse": "warn",
        "noNonNullAssertion": "warn",
        "noParameterAssign": "error",
        "noRestrictedGlobals": "error",
        "noShoutyConstants": "warn",
        "noUnusedTemplateLiteral": "error",
        "noVar": "error",
        "useBlockStatements": "warn",
        "useCollapsedElseIf": "warn",
        "useConst": "error",
        "useDefaultParameterLast": "error",
        "useEnumInitializers": "warn",
        "useExponentiationOperator": "error",
        "useFragmentSyntax": "error",
        "useNumericLiterals": "error",
        "useSelfClosingElements": "error",
        "useShorthandArrayType": "error",
        "useSingleVarDeclarator": "error",
        "useTemplate": "warn",
        "useWhile": "error"
      }
    }
  }
}

Key style rules:

```
noVar
```
: Use let/const instead of var
```
useConst
```
: Prefer const for immutable bindings
```
noNonNullAssertion
```
: Avoid ! assertions in TypeScript
```
useTemplate
```
: Prefer template literals

Suspicious

Rules for suspicious code patterns:

json

{
  "linter": {
    "rules": {
      "suspicious": {
        "recommended": true,
        "noArrayIndexKey": "warn",
        "noAssignInExpressions": "error",
        "noAsyncPromiseExecutor": "error",
        "noCatchAssign": "error",
        "noClassAssign": "error",
        "noCommentText": "error",
        "noCompareNegZero": "error",
        "noConsoleLog": "warn",
        "noControlCharactersInRegex": "error",
        "noDebugger": "error",
        "noDoubleEquals": "error",
        "noDuplicateCase": "error",
        "noDuplicateClassMembers": "error",
        "noDuplicateObjectKeys": "error",
        "noDuplicateParameters": "error",
        "noEmptyBlockStatements": "warn",
        "noExplicitAny": "warn",
        "noExtraNonNullAssertion": "error",
        "noFallthroughSwitchClause": "error",
        "noFunctionAssign": "error",
        "noGlobalAssign": "error",
        "noImportAssign": "error",
        "noLabelVar": "error",
        "noMisleadingCharacterClass": "error",
        "noPrototypeBuiltins": "error",
        "noRedeclare": "error",
        "noSelfCompare": "error",
        "noShadowRestrictedNames": "error",
        "noUnsafeNegation": "error",
        "useDefaultSwitchClauseLast": "error",
        "useGetterReturn": "error",
        "useValidTypeof": "error"
      }
    }
  }
}

Critical suspicious patterns:

```
noExplicitAny
```
: Avoid any in TypeScript
```
noConsoleLog
```
: Remove console.log in production
```
noDebugger
```
: Remove debugger statements
```
noDoubleEquals
```
: Use === instead of ==
```
noDuplicateObjectKeys
```
: Catch duplicate keys

Rule Configuration Patterns

Strict Configuration

Maximum strictness for high-quality codebases:

json

{
  "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,
        "noExplicitAny": "error",
        "noConsoleLog": "error"
      }
    }
  }
}

Gradual Adoption

Start lenient and progressively tighten:

json

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

Framework-Specific

React configuration example:

json

{
  "linter": {
    "rules": {
      "recommended": true,
      "a11y": { "recommended": true },
      "correctness": {
        "recommended": true,
        "noChildrenProp": "error"
      },
      "security": {
        "noDangerouslySetInnerHtml": "error"
      },
      "suspicious": {
        "noArrayIndexKey": "error"
      }
    }
  }
}

Ignoring Violations

Inline Comments

Suppress specific violations:

javascript

// biome-ignore lint/suspicious/noExplicitAny: Legacy code
function legacyFunction(data: any) {
  return data;
}

// biome-ignore lint/suspicious/noConsoleLog: Debug logging
console.log('Debug info');

// Multiple rules
// biome-ignore lint/suspicious/noExplicitAny lint/style/useConst: Migration
var config: any = {};

File-Level Ignores

Ignore entire file:

javascript

/* biome-ignore-file */

// Legacy file, skip all linting

Configuration Ignores

Ignore patterns in biome.json:

json

{
  "files": {
    "ignore": [
      "**/generated/**",
      "**/*.config.js",
      "**/vendor/**"
    ]
  }
}

Best Practices

Enable Recommended Rules - Start with
```
"recommended": true
```
Progressive Enhancement - Add stricter rules gradually
Document Exceptions - Explain why rules are disabled
Use Inline Ignores Sparingly - Prefer fixing over ignoring
Security First - Never disable security rules
CI Enforcement - Use
```
biome ci
```
in pipelines
Pre-commit Hooks - Catch issues before commit
Team Agreement - Discuss rule changes with team
Regular Review - Periodically review disabled rules
Fix Warnings - Don't let warnings accumulate

Common Pitfalls

Ignoring Errors - Using biome-ignore instead of fixing
Disabling Security - Turning off security rules
No CI Check - Not enforcing in continuous integration
Too Lenient - Setting everything to "warn"
No Documentation - Not explaining disabled rules
Inconsistent Config - Different rules per package
Ignoring Warnings - Treating warnings as optional
Wrong Rule Names - Typos in rule configuration
Overly Strict - Blocking team productivity
No Migration Plan - Enabling all rules at once

Advanced Topics

Custom Rule Sets

Create shared rule sets for organization:

json

{
  "extends": ["@company/biome-config"],
  "linter": {
    "rules": {
      "suspicious": {
        "noConsoleLog": "error"
      }
    }
  }
}

Per-Directory Rules

Use overrides for different code areas:

json

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

Migration Strategy

Migrating from ESLint:

Install Biome:
```
npm install -D @biomejs/biome
```
Initialize:
```
npx biome init
```
Run Check:
```
npx biome check .
```
to see violations
Fix Automatically:
```
npx biome check --write .
```
Address Remaining: Fix issues that can't auto-fix
Tune Rules: Adjust rules based on team needs
Update CI: Replace ESLint with Biome
Remove ESLint: After validation period

Integration Patterns

Package.json Scripts

json

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

Pre-commit Hook

Using husky:

json

{
  "husky": {
    "hooks": {
      "pre-commit": "biome check --write --changed"
    }
  }
}

GitHub Actions

yaml

- name: Run Biome
  run: npx biome ci .

Troubleshooting

False Positives

If rule triggers incorrectly:

Verify rule is appropriate for your code
Check if bug in Biome (report upstream)
Use biome-ignore with explanation
Consider disabling rule if widespread

Performance Issues

If linting is slow:

Update to latest Biome version
Use VCS integration
Ignore large generated directories
Check for file pattern issues

Rules Not Applied

Verify:

Linter is enabled in config
Rule category is enabled
Rule name is spelled correctly
No overrides disabling it
Files are not ignored

When to Use This Skill

Setting up linting for new projects
Migrating from ESLint to Biome
Configuring rule sets for teams
Troubleshooting linting errors
Optimizing code quality checks
Establishing code standards
Training team on Biome linting
Integrating linting into CI/CD

biome-linting

NPX Install

Tags

SKILL.md Content

Biome Linting

Overview

Core Commands

Basic Linting

Command Options

Rule Categories

Accessibility (a11y)

Complexity

Correctness

Performance

Security

Style

Suspicious

Rule Configuration Patterns

Strict Configuration

Gradual Adoption

Framework-Specific

Ignoring Violations

Inline Comments

File-Level Ignores

Configuration Ignores

Best Practices

Common Pitfalls

Advanced Topics

Custom Rule Sets

Per-Directory Rules

Migration Strategy

Integration Patterns

Package.json Scripts

Pre-commit Hook

GitHub Actions

Troubleshooting

False Positives

Performance Issues

Rules Not Applied

When to Use This Skill