Biome 16 🧹 The -include-inspired Flag — Porting rules that aren't exact matches - KandZ

⏱️ Estimated read: 12 min | |

The biome migrate eslint command reads an ESLint configuration and writes the equivalent Biome rules into the biome.json. The translation is not one-to-one, because Biome’s rule set is not a copy of ESLint’s. Each Biome rule is either identical to its ESLint source or only inspired by it, and the distinction determines whether the migration command ports the rule by default . The --include-inspired flag is the mechanism that opts into the broader set: without it, the command migrates only the identical rules; with it, the command also migrates the rules that Biome implements with a similar intent but a different behaviour.

Quick How-To Guides & Fast FixesNeed a quick fix or step-by-step solution? Browse our fast answers on HowTo.KandZ.me:

Operating Systems CLI →Dev Environment Languages →Web Network Tools →Security Accounts →Security Access Tech →Device Phone Basics →Social Messaging →Digital Files Media →

The flag exists because the inspired rules are not safe to port silently. An identical rule produces the same diagnostics and the same fixes as its ESLint source. An inspired rule produces similar diagnostics, but some options are not implemented, and some edge cases behave differently . The migration command cannot know whether the difference matters to the project, so the default is the conservative set—the identical rules—and the flag is the explicit opt-in to the broader set. The developer who passes the flag accepts the review obligation that comes with it.

Key point: By default, biome migrate eslint migrates only the rules that are identical to their ESLint sources. The --include-inspired flag adds the rules that Biome implements with a similar intent but a different behaviour. Even with the flag, the migrated rules do not behave exactly like ESLint, because some options are not implemented and some rules deliberately differ . The flag is the opt-in to the broader set, not the guarantee of the identical behaviour.

Why the flag exists

The identical-versus-inspired problem. Biome’s rule sources page classifies every rule as identical or inspired, and the classification is not cosmetic. An identical rule is the same check with the same semantics. An inspired rule is the same idea with a different implementation, and the difference can surface in the options the rule accepts, the edge cases it catches, or the fix it produces . The migration command reads the classification, and the flag is the mechanism that decides which side of the line the migration crosses.

The default-safety problem. A project that migrates from ESLint to Biome and runs the command without the flag gets a configuration that is a subset of the original. The subset is safe: the rules that are ported behave the same, and the rules that are not ported are simply absent. The absence is visible—the project can compare the old and the new rule lists—and the visibility is the mechanism that keeps the migration honest. The flag removes the safety, and the removal is the reason it is opt-in .

The option-gap problem. An inspired rule may not implement every option that the ESLint rule accepts. The import/no-duplicates rule is the concrete example: the migration maps it to the correctness/noDuplicateImports rule, but the mapping is marked as partial . The partial mapping is the mechanism that tells the developer that the rule is ported but the options are not, and the developer who passes the flag accepts the gap.

The review problem. The migration command writes the rules, but it cannot know whether the inspired rule’s behaviour is acceptable for the project. The review is the mechanism that catches the difference—the inspired rule that is stricter than the original, the inspired rule that is looser, the inspired rule that fixes differently. The flag is the opt-in to the review, not the replacement for it .

a. The flag in the migration command

The flag is passed to the biome migrate eslint command alongside the --write flag that applies the output.

# The default migration: the identical rules only
biome migrate eslint --write

# The migration with the inspired rules
biome migrate eslint --write --include-inspired

The default command reads the .eslintrc or the eslint.config.js, follows the extends chains, loads the plugins, and writes the identical rules into the biome.json . The flag extends the set to the inspired rules, and the extension is the mechanism that ports the rules that Biome implements with a different behaviour.

The migration command also has the --include-nursery flag, and the two flags are independent. The --include-inspired adds the inspired rules, and the --include-nursery adds the rules that are still in the nursery group. A project that wants both passes both flags .

# The migration with the inspired and the nursery rules
biome migrate eslint --write --include-inspired --include-nursery

The two flags are the different opt-ins, and the difference is the rule’s stability. The inspired rules are stable but different; the nursery rules are still under development. The project that passes the flag accepts the difference or the instability, and the acceptance is the review.

The migration output does not append the rules to the existing configuration. It sets the recommended preset to false and enables only the rules that it migrated . The replacement is the mechanism that keeps the configuration honest: the rules that the command did not migrate are not silently enabled by the preset, and the developer sees exactly which rules are active.

// The migrated biome.json (simplified)
{
  "linter": {
    "rules": {
      "recommended": false,
      "suspicious": {
        "noDoubleEquals": "error"
      }
    }
  }
}

The recommended: false is the replacement mechanism, and the noDoubleEquals is the migrated rule. The explicit set is the result of the translation, and the translation is the reason the flag matters.

b. The known differences and the post-migration review

The inspired rules do not behave exactly like their ESLint sources. The migration guide states the limitation explicitly: “Even with inspired rules, the result does not behave exactly like ESLint, because some rule options are not implemented and some rules deliberately differ” . The difference is the mechanism that makes the review necessary, and the review is the step that the flag does not replace.

The known differences fall into three categories. The option gap: the inspired rule accepts fewer options than the ESLint rule, and the options that are not implemented are silently dropped . The deliberate divergence: Biome has chosen to deviate from the ESLint behaviour in some rules, and the deviation is the intentional design, not the bug . The partial mapping: some rules are mapped with a note that the mapping is partial, such as the import/no-duplicates to the correctness/noDuplicateImports . The three categories are the review checklist, and the checklist is the mechanism that catches the difference.

The post-migration review is the manual step. The developer compares the old and the new rule lists, checks the inspired rules that were ported, and verifies the behaviour against the project’s expectations. The review is the mechanism that the flag does not remove, and the removal is the reason the flag is not the one-command-and-done.

The VCS integration is the separate step that the migration does not do automatically. The vcs.useIgnoreFile: true is the flag that makes Biome read the .gitignore, and the flag is the mechanism that keeps the ignore behaviour consistent with ESLint . The enablement is the mechanism that keeps the ignored files ignored, and the explicit step is the reason the migration is not the complete.

Complete Example Session

// ============================================
// PART 1: THE ESLINT CONFIGURATION
// ============================================

// .eslintrc.json
{
  "extends": ["eslint:recommended", "plugin:react/recommended"],
  "rules": {
    "eqeqeq": "error",
    "no-var": "error",
    "import/no-duplicates": "error"
  }
}

// ============================================
// PART 2: THE DEFAULT MIGRATION
// ============================================

// biome migrate eslint --write

// The command migrates the identical rules.
// The noDoubleEquals and the noVar are ported.
// The import/no-duplicates is not ported because the mapping is partial.

// ============================================
// PART 3: THE MIGRATION WITH THE INSPIRED RULES
// ============================================

// biome migrate eslint --write --include-inspired

// The command migrates the inspired rules as well.
// The import/no-duplicates is ported to the correctness/noDuplicateImports.
// The partial mapping is the known difference.

// ============================================
// PART 4: THE MIGRATED CONFIGURATION
// ============================================

// biome.json (simplified)
{
  "linter": {
    "rules": {
      "recommended": false,
      "suspicious": {
        "noDoubleEquals": "error"
      },
      "style": {
        "noVar": "error"
      },
      "correctness": {
        "noDuplicateImports": "error"
      }
    }
  }
}

// The recommended preset is disabled.
// The explicit rules are the migrated set.

// ============================================
// PART 5: THE PARTIAL MAPPING
// ============================================

// The import/no-duplicates is the partial mapping.
// The correctness/noDuplicateImports is the ported rule.
// The partial note is the known difference.

// ============================================
// PART 6: THE OPTION GAP
// ============================================

// The inspired rule may accept fewer options.
// The dropped options are the known difference.
// The review is the mechanism that catches the gap.

// ============================================
// PART 7: THE DELIBERATE DIVERGENCE
// ============================================

// Biome has chosen to deviate from the ESLint behaviour.
// The deviation is the intentional design.
// The review is the mechanism that verifies the acceptability.

// ============================================
// PART 8: THE NURSERY FLAG
// ============================================

// biome migrate eslint --write --include-inspired --include-nursery

// The nursery rules are also migrated.
// The two flags are the independent opt-ins.

// ============================================
// PART 9: THE VCS INTEGRATION
// ============================================

// biome.json — the added VCS configuration
{
  "vcs": {
    "enabled": true,
    "clientKind": "git",
    "useIgnoreFile": true
  }
}

// The .gitignore is respected.

// ============================================
// PART 10: THE CHECKLIST
// ============================================

// [ ] The default migration is run without the flag.
// [ ] The inspired rules are migrated with the flag.
// [ ] The partial mappings are reviewed.
// [ ] The option gaps are reviewed.
// [ ] The deliberate divergences are reviewed.
// [ ] The VCS integration is enabled.
// [ ] The migrated rules are tested against the project's expectations.

The ten parts covered the ESLint configuration, the default migration, the migration with the inspired rules, the migrated configuration, the partial mapping, the option gap, the deliberate divergence, the nursery flag, the VCS integration, and the checklist. The through-line is that the flag is the opt-in to the broader set, and the review is the mechanism that catches the difference.

Quick Reference

The migration flags

Flag	Effect
`--write`	Apply the migration to the `biome.json`
`--include-inspired`	Migrate the inspired rules
`--include-nursery`	Migrate the nursery rules

The rule classification

Classification	Behaviour	Migrated by default
Identical	The same as the ESLint source	Yes
Inspired	Similar, with the differences	No, requires the flag
Nursery	Still under development	No, requires the flag

The known differences

Difference	Detail
The option gap	Some options are not implemented
The deliberate divergence	Some rules differ by design
The partial mapping	Some rules are mapped with a note

The post-migration steps

Step	Purpose
Enable the VCS	Keep the `.gitignore` behaviour
Review the rule list	Catch the difference
Test the behaviour	Verify the acceptability

Best Practices

✅ Do This:

# Start with the default migration
biome migrate eslint --write                                      // ✅

# Add the inspired rules only after the review
biome migrate eslint --write --include-inspired                    // ✅

# Enable the VCS integration for the .gitignore
{ "vcs": { "useIgnoreFile": true } }                              // ✅

❌ Don’t Do This:

# Assume the inspired rules behave exactly like ESLint
biome migrate eslint --write --include-inspired // the review is still needed // ❌

# Skip the VCS integration
// The .gitignore files are processed                              // ❌

Common Pitfalls

Pitfall	Why It Happens	Fix
The rule is missing	The default migrates only the identical rules	Use the `--include-inspired` flag
The behaviour differs	The rule is inspired, not identical	Review the rule source page
The option is ignored	The option is not implemented	Configure the rule by hand
The `.gitignore` is not respected	The VCS integration is disabled	Enable the `vcs.useIgnoreFile`

Real-World Examples

1. The default migration

biome migrate eslint --write

2. The migration with the inspired rules

biome migrate eslint --write --include-inspired

3. The migration with the nursery rules

biome migrate eslint --write --include-inspired --include-nursery

4. The identical rule

{ "suspicious": { "noDoubleEquals": "error" } }

5. The inspired rule

{ "correctness": { "noDuplicateImports": "error" } }

6. The recommended preset

{ "linter": { "rules": { "recommended": false } } }

7. The partial mapping

The import/no-duplicates is the partial mapping.

8. The VCS integration

{ "vcs": { "useIgnoreFile": true } }

9. The rule source page

The rule source page lists the identical and the inspired rules.

10. The review

The migrated rules are reviewed against the project's expectations.

Visual

The Migration Set

┌──────────────────────────────────────────────────────────────┐
│  THE MIGRATION SET                                           │
│                                                              │
│  The default:                                                │
│  ┌─────────────────────┐                                    │
│  │ The identical rules │  The safe subset                   │
│  └──────────┬──────────┘                                    │
│             │                                                │
│             ▼                                                    │
│  ┌─────────────────────┐                                    │
│  │ The inspired rules  │  The --include-inspired adds them  │
│  └──────────┬──────────┘                                    │
│             │                                                │
│             ▼                                                    │
│  ┌─────────────────────┐                                    │
│  │ The nursery rules   │  The --include-nursery adds them   │
│  └─────────────────────┘                                    │
└──────────────────────────────────────────────────────────────┘

The Known Difference

┌──────────────────────────────────────────────────────────────┐
│  THE KNOWN DIFFERENCE                                        │
│                                                              │
│  The inspired rule:                                          │
│  ┌─────────────────────┐                                    │
│  │ The same idea       │  The different behaviour           │
│  │ The fewer options   │                                    │
│  │ The different edge  │                                    │
│  └──────────┬──────────┘                                    │
│             │                                                │
│             ▼                                                    │
│  ┌─────────────────────┐                                    │
│  │ The review          │  The mechanism that catches it     │
│  └─────────────────────┘                                    │
└──────────────────────────────────────────────────────────────┘

The Partial Mapping

┌──────────────────────────────────────────────────────────────┐
│  THE PARTIAL MAPPING                                         │
│                                                              │
│  The import/no-duplicates                                    │
│         │                                                    │
│         ▼                                                    │
│  ┌─────────────────────┐                                    │
│  │ The correctness/    │  The ported rule                   │
│  │ noDuplicateImports  │  The partial mapping               │
│  └──────────┬──────────┘                                    │
│             │                                                │
│             ▼                                                    │
│  ┌─────────────────────┐                                    │
│  │ The options are     │  The known difference              │
│  │ not all implemented │                                    │
│  └─────────────────────┘                                    │
└──────────────────────────────────────────────────────────────┘

Summary

Item	Value
The command	`biome migrate eslint`
The default set	The identical rules only
The flag	`--include-inspired`
The nursery flag	`--include-nursery`
The known difference	The option gap, the deliberate divergence, the partial mapping
The post-migration	The VCS integration, the review, the test

Key takeaways:

The --include-inspired flag is the opt-in to the broader rule set. By default, the migration ports only the rules that are identical to their ESLint sources. The flag adds the rules that Biome implements with a similar intent but a different behaviour .
The inspired rules do not behave exactly like ESLint. Some options are not implemented, and some rules deliberately differ. The flag is the opt-in to the broader set, not the guarantee of the identical behaviour .
The partial mappings are the known difference. Some rules are mapped with a note that the mapping is partial, such as the import/no-duplicates to the correctness/noDuplicateImports . The partial note is the mechanism that tells the developer that the rule is ported but the options are not.
The nursery flag is the separate opt-in. The --include-nursery adds the rules that are still under development. The two flags are independent, and the project that wants both passes both .
The review is the mechanism that the flag does not replace. The migration writes the rules, and the developer checks the output against the project’s expectations. The review is the step that catches the inspired rule that is stricter, looser, or different from the original.

Remember: The Biome ESLint migration is the command that ports the configuration, and the --include-inspired flag is the opt-in to the broader set. The default is the identical rules, and the flag adds the inspired rules that behave differently. The review is the mechanism that catches the difference, and the VCS integration keeps the ignore behaviour. The flag is the opt-in, not the guarantee.

Was this helpful?

Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!