How `adoptExistingLintConfig` Integrates ESLint and Oxlint Configurations in React-Doctor

When enabled, adoptExistingLintConfig automatically imports your project's existing ESLint (.eslintrc.json) or Oxlint (.oxlintrc.json) rules into the React-Doctor analysis by detecting config files, filtering incompatible package references, and merging them into a temporary Oxlint configuration that contributes to your health score.

The adoptExistingLintConfig option in the millionco/react-doctor repository controls whether the tool respects your existing linting setup or relies solely on its curated rule set. This boolean flag—defined in packages/react-doctor/src/types.ts—defaults to true and triggers a multi-stage pipeline that safely bridges ESLint configurations with Oxlint's execution engine.

How adoptExistingLintConfig Works: The 4-Step Pipeline

When set to true (the default), the option triggers a multi-stage process defined across several utility modules in packages/react-doctor/src/utils/.

Step 1: Detecting User Lint Configurations

The detectUserLintConfigPaths function walks upward from the scanned directory looking for the first adoptable config file. According to packages/react-doctor/src/utils/detect-user-lint-config.ts (lines 7-33), it recognizes .oxlintrc.json, .eslintrc.json, and other supported formats, stopping at a project boundary marked by .git or a monorepo root.

// From packages/react-doctor/src/utils/detect-user-lint-config.ts
const paths = detectUserLintConfigPaths("/path/to/project");
// Returns: ["/path/to/project/.oxlintrc.json"]

Step 2: Filtering Unsupported ESLint Extends

If the detected file is an ESLint JSON config, canOxlintExtendConfig parses it—supporting JSONC comments—and validates the "extends" array. According to the source in packages/react-doctor/src/utils/can-oxlint-extend-config.ts (lines 68-80), only local-path extends (such as "./..", "../..", or absolute paths) are retained. Pure package references like "next" or "airbnb" are silently dropped because Oxlint's resolver cannot handle bare package names, which would cause a parser error and a misleading "could not adopt existing lint config" warning.

Step 3: Building the Temporary Oxlint Config

The runOxlint function in packages/react-doctor/src/utils/run-oxlint.ts (lines 41-55) constructs a temporary oxlintrc.json. When adoption is enabled, it injects the filtered user config paths into the "extends" field alongside the React-Doctor plugin.

{
  "plugins": [{ "name": "react-doctor", "specifier": "react-doctor/oxlint-plugin" }],
  "extends": [
    "/abs/path/to/.oxlintrc.json"
  ]
}

Step 4: Running Oxlint with Merged Rules

Oxlint executes using the temporary configuration, processing its own rules plus the adopted user rules. Any diagnostics triggered by your custom rules count toward the overall React-Doctor health score. If adoptExistingLintConfig is disabled, this merge step is skipped entirely, and only the curated React-Doctor rule set applies.

Configuration Examples

Disabling Config Adoption

Create or modify react-doctor.config.json to ignore existing lint configs:

{
  "adoptExistingLintConfig": false
}

Result: React-Doctor will not search for .eslintrc.json or .oxlintrc.json files, scanning only with built-in rules.

Enabling Adoption (Default)

Omit the key or explicitly set it to true:

{
  // Defaults to true
}

Result: The tool automatically detects and merges your existing lint configurations into the Oxlint execution.

CLI Overrides

Override the configuration file setting for a single run:

react-doctor ./my-app --no-adopt-existing-lint-config

Result: Same effect as setting the configuration key to false for that specific invocation.

Technical Implementation Details

The complete lifecycle involves these key files in the millionco/react-doctor source:

• packages/react-doctor/src/types.ts (lines 70-92): Defines the ReactDoctorConfig interface including the adoptExistingLintConfig boolean with documentation.
• packages/react-doctor/src/utils/detect-user-lint-config.ts (lines 7-33): Implements the directory traversal logic that finds adoptable configs while respecting project boundaries.
• packages/react-doctor/src/utils/can-oxlint-extend-config.ts (lines 68-80): Contains the filtering logic that prevents Oxlint from attempting to resolve bare package names in ESLint extends.
• packages/react-doctor/src/utils/run-oxlint.ts (lines 41-55): Builds the temporary Oxlint configuration and handles the extends array merging.
• packages/react-doctor/README.md (lines 40-42): Documents the option and its default value for end users.

Summary

• adoptExistingLintConfig defaults to true and controls whether React-Doctor imports existing ESLint/Oxlint configurations.
• The detection process walks upward from the scan directory and stops at project boundaries to avoid inheriting configs from outside the repository.
• ESLint configs undergo filtering to remove package-reference extends (like "airbnb"), keeping only local file paths that Oxlint can resolve.
• Merged configurations are injected into a temporary oxlintrc.json that includes the React-Doctor plugin rules.
• Diagnostics from adopted rules contribute to the final health score, or you can disable adoption to use only curated rules.

Frequently Asked Questions

What happens if I have both ESLint and Oxlint configs?

React-Doctor will detect whichever config file it encounters first during its upward directory traversal. The detectUserLintConfigPaths utility stops at the first match, so the configuration closest to your project root typically takes precedence.

Why are some ESLint extends filtered out?

The canOxlintExtendConfig function filters out bare package references (e.g., "next", "eslint:recommended") because Oxlint's resolver only understands local file paths. Attempting to extend a package name would cause Oxlint to crash with a parser error, so React-Doctor silently drops these references to ensure stability.

Can I use adoptExistingLintConfig in a monorepo?

Yes. The detection algorithm stops at monorepo roots, preventing sub-packages from unintentionally inheriting lint configurations from parent directories outside the repository. This boundary detection ensures safe adoption in complex repository structures.

How does this affect my React-Doctor health score?

When enabled, any linting errors or warnings triggered by your adopted ESLint or Oxlint rules are counted alongside React-Doctor's built-in diagnostics. This means your existing coding standards directly influence the health score. Disabling the option isolates the score to only React-Doctor's curated rules.

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