React Doctor ignore.overrides vs ignore.files vs ignore.rules: Configuration Guide

React Doctor evaluates three distinct suppression mechanisms—ignore.rules for global rule disabling, ignore.files for path-based exclusion, and ignore.overrides for granular file-and-rule combinations—in a specific sequence to determine which diagnostics appear in your final report.

The millionco/react-doctor toolchain analyzes React projects for anti-patterns and potential bugs, but generated code and third-party directories often trigger false positives. Understanding the precise distinctions between ignore.overrides, ignore.files, and ignore.rules allows you to silence diagnostics surgically without weakening checks across your production codebase. Each mechanism serves a unique scope, from codebase-wide rule suppression to targeted exclusions in specific file patterns.

ignore.rules (Global Rule Suppression)

The ignore.rules configuration accepts an array of rule IDs and suppresses those diagnostics everywhere they appear. When React Doctor initializes, it compiles these IDs into a Set called ignoredRules during the filterIgnoredDiagnostics phase.

According to the source in packages/react-doctor/src/utils/filter-diagnostics.ts (lines 185‑188), any diagnostic whose rule property matches an entry in this set is removed immediately, regardless of file location. This provides the broadest suppression scope and takes precedence before file-level filtering occurs.

{
  "ignore": {
    "rules": ["react/no-danger"]
  }
}

Effect: Every instance of the react/no-danger rule is silenced across the entire project.

ignore.files (Path-Based Exclusion)

The ignore.files configuration accepts glob patterns and excludes every diagnostic found in matching file paths. The engine compiles these patterns into regular expressions via compileIgnoredFilePatterns, then tests each diagnostic’s file path against them using isFileIgnoredByPatterns.

This logic resides in packages/react-doctor/src/utils/is-ignored-file.ts. Unlike ignore.rules, which targets specific rule IDs, this mechanism targets locations—meaning every rule is suppressed for files matching the specified patterns.

{
  "ignore": {
    "files": ["src/generated/**"]
  }
}

Effect: All diagnostics in any file under src/generated/ are ignored, regardless of which rule triggered them.

ignore.overrides (Granular File and Rule Control)

The ignore.overrides configuration provides the most surgical control, accepting an array of objects with files (required) and rules (optional) properties. The implementation in packages/react-doctor/src/utils/apply-ignore-overrides.ts validates these entries via compileIgnoreOverrides and applies them via isDiagnosticIgnoredByOverrides.

This mechanism operates in two modes:

• With rules specified: Only the listed rules are silenced for the matched files.
• Without rules specified: All rules are silenced for the matched files, functioning identically to ignore.files but scoped to that entry only.

When rules is omitted, line 77 in apply-ignore-overrides.ts evaluates override.ruleIds.size === 0 || override.ruleIds.has(ruleId). Since the set size is zero, the condition evaluates true for every rule ID, effectively suppressing everything.

{
  "ignore": {
    "overrides": [
      {
        "files": ["src/legacy/**"],
        "rules": ["react/no-danger", "react/no-direct-mutation-state"]
      }
    ]
  }
}

Effect: Inside src/legacy/, only the two specified rules are ignored; all other diagnostics remain active.

To suppress all rules for a specific directory, omit the rules array:

{
  "ignore": {
    "overrides": [
      { "files": ["node_modules/some-lib/**"] }
    ]
  }
}

Evaluation Order and Interaction

React Doctor applies these filters in a strict pipeline within filter-diagnostics.ts:

1. Global rules first – Diagnostics matching ignore.rules are removed immediately.
2. File patterns second – Remaining diagnostics are checked against ignore.files; matches are discarded.
3. Overrides last – The isDiagnosticIgnoredByOverrides function evaluates remaining diagnostics against the compiled override entries.

This sequence guarantees that a rule listed in ignore.rules can never reappear via an override. Overrides only affect diagnostics that survived the first two filtering stages, meaning they cannot re-enable globally disabled rules.

Summary

• ignore.rules suppresses specific rule IDs across the entire codebase via a global Set evaluated in filter-diagnostics.ts.
• ignore.files excludes all diagnostics from file paths matching glob patterns, compiled and tested in is-ignored-file.ts.
• ignore.overrides provides targeted suppression using { files, rules? } objects; omitting rules silences everything for those files.
• The evaluation order is global rules → file patterns → overrides, ensuring overrides cannot resurrect globally ignored diagnostics.

Frequently Asked Questions

Can I use glob patterns in ignore.rules?

No. The ignore.rules array accepts only rule ID strings (e.g., react/no-danger), not glob patterns. To exclude by file path, use ignore.files or ignore.overrides.

Does ignore.overrides take precedence over ignore.rules?

No. Rules listed in ignore.rules are filtered out before overrides are evaluated. Once a rule is globally suppressed, it cannot be re-enabled for specific files using ignore.overrides.

What happens if I omit the rules array in an ignore.overrides entry?

When the rules property is omitted, the override entry suppresses all diagnostics for the matched files. According to line 77 in apply-ignore-overrides.ts, an empty ruleIds set causes the function to return true for every rule ID, effectively acting as a file-level exclusion.

Where does React Doctor compile these ignore patterns?

The compilation occurs in three specific locations: filter-diagnostics.ts handles the ignoredRules Set (lines 185‑188), is-ignored-file.ts compiles glob patterns into RegExp via compileIgnoredFilePatterns, and apply-ignore-overrides.ts validates and compiles override entries via compileIgnoreOverrides.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}