/migration-patterns:eslint-to-biome

Migrate from ESLint (and optionally Prettier) to Biome — a fast, unified linter and formatter for JavaScript/TypeScript written in Rust. Migrates configuration, updates pre-commit hooks, and removes old dependencies.

When to Use This Skill

Use this skill when...	Keep ESLint when...
`biome.json` does not exist yet	You rely on an ESLint plugin with no Biome equivalent (e.g., `eslint-plugin-react-hooks`, `eslint-plugin-jsx-a11y`)
`.eslintrc` or `eslint.config.` exists	CI requires ESLint's exit codes specifically
You also want to replace Prettier with Biome formatter	Team has invested in custom ESLint rules
Using TypeScript and want a single tool

Important: Biome covers ~90% of common ESLint rules but not all plugins. Audit eslint-plugin-* dependencies before migrating. The most common unsupported plugins are accessibility (jsx-a11y) and framework hooks (react-hooks). You may need to keep ESLint alongside Biome for these.

Context

ESLint configs: !find . -maxdepth 2 \( -name '.eslintrc' -o -name '.eslintrc.js' -o -name '.eslintrc.cjs' -o -name '.eslintrc.json' -o -name '.eslintrc.yaml' -o -name '.eslintrc.yml' -o -name 'eslint.config.js' -o -name 'eslint.config.mjs' -o -name 'eslint.config.ts' \)
Prettier configs: !find . -maxdepth 2 \( -name '.prettierrc' -o -name '.prettierrc.js' -o -name '.prettierrc.json' -o -name 'prettier.config.js' \)
Biome config: !find . -maxdepth 2 -name 'biome.json'
package.json: !find . -maxdepth 1 -name 'package.json'
Pre-commit config: !find . -maxdepth 1 -name '.pre-commit-config.yaml'

Parameters

Parameter	Description
`--check-only`	Report what would change without modifying files
`--fix`	Apply migration automatically

Execution

Execute this ESLint-to-Biome migration:

Step 1: Audit current ESLint/Prettier configuration

Read all ESLint config files found in context.
Read Prettier config files if present.
Check package.json for eslint* and prettier* dependencies.

Report findings:

ESLint → Biome migration audit
================================
ESLint config:    .eslintrc.json (N rules, plugins: [...])
Prettier config:  .prettierrc (printWidth=N, singleQuote=true)
ESLint plugins:   eslint-plugin-import, @typescript-eslint, ...
Biome support:    ✓ eslint-plugin-import → Biome handles this
                  ⚠ eslint-plugin-jsx-a11y → No Biome equivalent (keep ESLint for this)
biome.json:       NOT PRESENT

If --check-only, stop here.

Step 2: Check plugin compatibility

For each eslint-plugin-* found, determine Biome coverage:

ESLint plugin	Biome equivalent
`@typescript-eslint`	Biome has TypeScript-aware rules (`nursery/use*`, `suspicious/`, `correctness/`)
`eslint-plugin-import`	Biome `correctness/noUndeclaredDependencies`, `correctness/noUnusedImports`
`eslint-plugin-unicorn`	Biome has partial coverage via `style/` rules
`eslint-plugin-jsx-a11y`	Not covered by Biome — keep ESLint for accessibility
`eslint-plugin-react-hooks`	Not covered by Biome — keep ESLint for hooks rules
`eslint-plugin-security`	Partial coverage in Biome `security/` rules

If unsupported plugins are found, ask the user whether to proceed with a partial migration (keep ESLint only for those plugins). If the user declines, abort.

Step 3: Create biome.json

Generate biome.json preserving equivalent rules from the existing ESLint and Prettier configurations:

{
  "$schema": "https://biomejs.dev/schemas/1.9.0/schema.json",
  "organizeImports": {
    "enabled": true
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true
    }
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 80
  },
  "javascript": {
    "formatter": {
      "quoteStyle": "double",
      "trailingCommas": "all",
      "semicolons": "always"
    }
  }
}

Adjust these defaults to match the Prettier config found in Step 1:

lineWidth → from printWidth
quoteStyle → from singleQuote: true → "single"
trailingCommas → from trailingComma: "es5" → "es5"
semicolons → from semi: false → "asNeeded"
indentStyle → from useTabs: true → "tab"

Step 4: Update package.json

Remove ESLint and Prettier dev dependencies (if doing full migration):

"devDependencies": {
  remove: eslint, @typescript-eslint/parser, @typescript-eslint/eslint-plugin,
          eslint-plugin-import, prettier, eslint-config-prettier, eslint-plugin-prettier
  keep: eslint-plugin-jsx-a11y, eslint-plugin-react-hooks (if partial migration)
}

Add Biome:
```
"@biomejs/biome": "^1.9.0"
```

Update scripts in package.json:

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

Step 5: Update .pre-commit-config.yaml (if present)

Remove any ESLint/Prettier pre-commit hooks. Add Biome:

- repo: https://github.com/biomejs/pre-commit
  rev: v0.6.0  # use latest
  hooks:
    - id: biome-check
      additional_dependencies: ["@biomejs/biome@1.9.0"]

Step 6: Delete old config files

Remove ESLint and Prettier config files (unless keeping ESLint for unsupported plugins — in that case, keep .eslintrc but note Biome replaces most rules):

.eslintrc* → delete (if full migration)
eslint.config.* → delete (if full migration)
.prettierrc* → delete
.eslintignore → convert relevant patterns to biome.json ignore section

Step 7: Verify migration

Run Biome to confirm it works:

npx @biomejs/biome check .
# or with bun:
bunx @biomejs/biome check .

Address any errors that weren't caught by ESLint (Biome may surface additional issues). Errors on first run are expected — fix them or add to biome.json ignore rules.

Step 8: Report

Print a summary:

ESLint → Biome migration complete
===================================
biome.json                CREATED
package.json              UPDATED (added @biomejs/biome, removed eslint/prettier)
.eslintrc.json            DELETED / KEPT (partial migration)
.prettierrc               DELETED
.pre-commit-config.yaml   UPDATED (added biome-check hook)

Partial migration note (if applicable):
  Kept eslint-plugin-jsx-a11y and eslint-plugin-react-hooks — these plugins
  have no Biome equivalent. ESLint is still needed for these rules.

Files to stage:
  git add biome.json package.json .pre-commit-config.yaml
  git add <deleted config files>

Agentic Optimizations

Context	Command
Audit only	`/migration-patterns:eslint-to-biome --check-only`
Apply migration	`/migration-patterns:eslint-to-biome --fix`
Check with Biome	`npx @biomejs/biome check .`
Format with Biome	`npx @biomejs/biome format --write .`

Quick Reference

Item	Value
Biome docs	https://biomejs.dev/
ESLint migration guide	https://biomejs.dev/guides/migrate-eslint-prettier/
Config schema	`https://biomejs.dev/schemas/1.9.0/schema.json`
Pre-commit hook	`biomejs/pre-commit`

eslint-to-biome