biome-typescript

name	biome-typescript
description	Configure and use Biome (biomejs) for TypeScript linting and formatting. Use when setting up Biome in a project, configuring lint rules, migrating from ESLint/Prettier, fixing lint errors, setting up CI pipelines with Biome, or configuring git hooks for code quality. Covers biome.json configuration, file inclusion/exclusion patterns, rule overrides, and integration with build tooling.

Biome TypeScript Linting Skill

Routing Guide

Task	Section
Install or update Biome	Version Discovery
Initial setup	Quick Start
Configure rules	Configuration Patterns
Include/exclude files	File Targeting
Fix specific lint errors	See references/lint-solutions.md
Stricter rules beyond recommended	See references/strict-rules.md
Migrate from ESLint/Prettier	See references/migration.md
CI and git hooks	See references/ci-hooks.md

Version Discovery

Never trust cached knowledge of Biome versions. Query the npm registry:

npm view @biomejs/biome version

Or for all recent versions:

npm view @biomejs/biome versions --json | tail -20

Check release notes for breaking changes:

curl -s https://api.github.com/repos/biomejs/biome/releases/latest | jq -r '.tag_name, .html_url'

Quick Start

Install as dev dependency (always pin exact version):

npm install --save-dev --save-exact @biomejs/biome@latest
npx biome init

This creates biome.json. Immediately verify:

npx biome check .

Minimal biome.json

{
  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
  "vcs": {
    "enabled": true,
    "clientKind": "git",
    "useIgnoreFile": true
  },
  "organizeImports": {
    "enabled": true
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true
    }
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2
  }
}

Critical: Update the $schema URL to match your installed version.

Configuration Patterns

Rule Severity Levels

{
  "linter": {
    "rules": {
      "recommended": true,
      "suspicious": {
        "noExplicitAny": "error",
        "noArrayIndexKey": "warn"
      },
      "style": {
        "noNonNullAssertion": "off"
      }
    }
  }
}

Levels: "error" | "warn" | "off"

Rules with Options

Some rules accept configuration objects:

{
  "linter": {
    "rules": {
      "style": {
        "useNamingConvention": {
          "level": "error",
          "options": {
            "strictCase": false,
            "conventions": [
              {
                "selector": { "kind": "variable" },
                "formats": ["camelCase", "CONSTANT_CASE"]
              }
            ]
          }
        }
      },
      "complexity": {
        "noExcessiveCognitiveComplexity": {
          "level": "error",
          "options": {
            "maxAllowedComplexity": 15
          }
        }
      }
    }
  }
}

Extending Configurations

{
  "extends": ["./biome.base.json"]
}

Arrays merge; later entries override earlier ones.

File Targeting (Rough Edges)

Global Include/Exclude

Top-level files applies to all tools (linter, formatter, organizeImports):

{
  "files": {
    "include": ["src/**", "tests/**"],
    "ignore": ["**/generated/**", "**/*.d.ts", "**/dist/**"]
  }
}

Gotcha: Patterns are relative to biome.json location. Use **/ prefix for recursive matching.

Tool-Specific Include/Exclude

Each tool can have its own file scope:

{
  "linter": {
    "include": ["src/**"],
    "ignore": ["src/generated/**"]
  },
  "formatter": {
    "include": ["src/**", "scripts/**"],
    "ignore": ["src/vendor/**"]
  }
}

Per-File Rule Overrides

Apply different rules to specific file patterns:

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

Critical ordering: Overrides apply in array order. Later overrides win for the same file.

VCS Integration

Let Biome respect .gitignore:

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

With useIgnoreFile: true, anything in .gitignore is automatically excluded.

Command Reference

# Check without modifying (CI mode)
npx biome check .

# Fix all auto-fixable issues
npx biome check --write .

# Lint only (no formatting)
npx biome lint .

# Format only
npx biome format --write .

# Organize imports only
npx biome check --organize-imports-enabled=true --write .

# Check specific files
npx biome check src/index.ts src/utils/**/*.ts

# Output as JSON (for tooling)
npx biome check --reporter=json .

# Show which files would be processed
npx biome check --files-ignore-unknown=true --no-errors-on-unmatched .

Useful Flags

Flag	Purpose
--write	Apply fixes
--unsafe	Apply unsafe fixes (review carefully)
--staged	Only check git-staged files
--changed	Only check files changed since default branch
--reporter=json	Machine-readable output
--diagnostic-level=error	Exit non-zero only on errors (ignore warnings)

Suppression Comments

Suppress specific rules inline:

// biome-ignore lint/suspicious/noExplicitAny: external API requires any
const response: any = await legacyApi.fetch();

// biome-ignore lint/style/noNonNullAssertion: checked above
const element = document.getElementById("root")!;

Always include a reason after the colon. Biome enforces this—reasonless suppressions fail.

Avoid these lazy patterns:

// BAD: Will need revisiting
// biome-ignore lint/suspicious/noExplicitAny: TODO fix later
// biome-ignore lint/suspicious/noExplicitAny: too complex to type

// GOOD: Explains why suppression is necessary
// biome-ignore lint/suspicious/noExplicitAny: FFI boundary with untyped C library
// biome-ignore lint/suspicious/noExplicitAny: generic deserializer, caller provides type

Package.json Scripts

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

TypeScript Integration

Biome does not use tsconfig.json for path resolution by default. For monorepos or path aliases:

{
  "javascript": {
    "jsxRuntime": "reactClassic",
    "globals": ["React"]
  }
}

For JSX:

{
  "javascript": {
    "jsxRuntime": "automatic"
  }
}

When to Consult Reference Files

• Struggling with a specific lint error? → references/lint-solutions.md
• Want stricter rules than "recommended"? → references/strict-rules.md
• Migrating from ESLint or Prettier? → references/migration.md
• Setting up CI or git hooks? → references/ci-hooks.md