/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": {
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
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 .
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
See Also
/migration-patterns:black-to-ruff-format — Python formatter migration (analogous pattern)
/configure:repo — End-to-end repo config driver