Eslint Knowledge Patch

ESLint Knowledge Patch

Load this skill when upgrading ESLint, migrating configuration, maintaining custom rules or formatters, updating rule tests, or debugging typed and AST integrations. Start with the breaking-change checks, then open the reference that matches the work.

Reference index

Upgrade triage

For an ESLint 10 upgrade, check these areas in order:

1. Confirm Node.js is at least 20.19.0 and is not a 21.x or 23.x release.
2. Require Jiti 2.2.0 or later when it loads a TypeScript config.
3. Remove .eslintrc.*, .eslintignore, /* eslint-env */, and deleted legacy CLI flags.
4. Resolve configuration from each linted file's directory, not from the invocation directory.
5. Update custom rules away from removed context and SourceCode APIs.
6. Repair RuleTester cases and select deliberate assertionOptions.
7. Re-run the recommended configuration and review newly enabled rules.
8. For typed integrations, require TypeScript 5.3 or later and review the bundled Espree and ESLint Scope declarations.

Runtime gates

ESLint 10 does not support:

• Node.js versions earlier than 20.19.0;
• any Node.js 21.x release;
• any Node.js 23.x release.

TypeScript configuration loading through Jiti requires Jiti 2.2.0 or later. Check the runtime used by local scripts and every CI job before investigating config-load failures.

Configuration is resolved per linted file

Configuration lookup starts beside each linted file. One command can therefore select different eslint.config.* files for targets in different directories.

When files behave differently:

1. Start at the first target file's directory.
2. Determine which config is discovered from there.
3. Repeat for each other target.
4. Do not use the process working directory as the lookup anchor.

The v10_config_lookup_from_file feature flag is gone because this behavior is the default.

Flat configuration is the only configuration system

Do not fall back to eslintrc behavior in ESLint 10.

The programmatic legacy surface is removed too:

• loadESLint() always returns ESLint.
• Linter rejects configType: "eslintrc".
• Linter#defineParser(), defineRule(), defineRules(), and getRules() are unavailable.
• /use-at-your-own-risk no longer exports LegacyESLint or FileEnumerator.
• shouldUseFlatConfig() always returns true.

Replace removed rule APIs

Use properties in place of removed context accessors:

context.parserPath has no replacement.

Use these SourceCode replacements:

SourceCode#getJSDocComment() has no replacement. Treat both no-replacement cases as integration redesign points.

Make RuleTester expectations explicit

RuleTester#run() accepts assertionOptions:

• requireMessage: true accepts either message or messageId.
• requireMessage: "message" requires message.
• requireMessage: "messageId" requires messageId.
• requireLocation: true requires both line and column.
• requireData: true requires data when the selected messageId template contains placeholders.

ruleTester.run("my-rule", rule, {
  valid: [],
  invalid: [{
    code: "foo",
    errors: [{
      messageId: "unexpected",
      data: { name: "foo" },
      line: 1,
      column: 1
    }]
  }],
  assertionOptions: {
    requireMessage: "messageId",
    requireLocation: true,
    requireData: true
  }
});

Choose strictness to match the rule's public test contract. Inspect the message template before deciding whether requireData requires a data object.

Language-aware configuration and rules

Configuration objects can set language. Rule metadata can set meta.languages to declare language compatibility. Use both when configuring non-JavaScript language plugins or publishing a multi-language rule.

With ES2026 globals enabled, Temporal is defined but non-callable. no-obj-calls reports Temporal() instead of treating Temporal as an undefined name.

TypeScript-specific rule behavior

max-params supports countThis: "never", which excludes a TypeScript this parameter and supersedes the deprecated countVoidThis option.

export default [{
  rules: {
    "max-params": ["error", { max: 2, countThis: "never" }]
  }
}];

no-var can fix declarations inside TSModuleBlock. It withholds the autofix when a variable is used before its declaration, avoiding an unsafe conversion.

Re-check rule results after patch upgrades

In 10.8.1, removal edits from no-unused-labels and the removeVar suggestion from no-unused-vars avoid automatic-semicolon-insertion hazards. The edits no longer risk joining adjacent syntax into a different parse.

Also in 10.8.1:

• id-denylist and id-match ignore grammar-defined meta-property names such as meta in import.meta and target in new.target.
• getter-return and accessor-pairs avoid corrected false positives.

Revisit suppressions or disabled rules that worked around those diagnostics.

Integration checks

• JSX component identifiers are ordinary scope references. Scope-based rules should neither mark a JSX-only import unused nor miss an undefined JSX name.
• Program.range covers the entire source, including leading and trailing comments and whitespace.
• Espree 11.1.0 and ESLint Scope 9.1.0 provide built-in types. Remove redundant @types/espree and @types/eslint-scope declarations carefully because the bundled types are not identical.
• Formatter format() receives explicit color: true or color: false in its second argument for --color or --no-color.
• Bulk-suppression functionality is available programmatically; integrations need not shell out to the CLI workflow.

Final migration check

The ESLint 10 eslint:recommended set enables additional rules, so new diagnostics do not necessarily mean configuration discovery failed. Run lint without changing configuration first and classify the new findings.

ESLint 9.x receives only critical, security, and cross-major compatibility fixes during maintenance and reaches end of life on 2026-08-06. Use that date when evaluating a deferred migration.