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

> Learn how adoptExistingLintConfig integrates ESLint and Oxlint configs into React Doctor. It imports your rules, filters incompatibilities, and merges them for a better health score.

- Repository: [Million Software, Inc./react-doctor](https://github.com/millionco/react-doctor)
- Tags: internals
- Published: 2026-05-12

---

**When enabled, `adoptExistingLintConfig` automatically imports your project's existing ESLint ([`.eslintrc.json`](https://github.com/millionco/react-doctor/blob/main/.eslintrc.json)) or Oxlint ([`.oxlintrc.json`](https://github.com/millionco/react-doctor/blob/main/.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`](https://github.com/millionco/react-doctor/blob/main/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`](https://github.com/millionco/react-doctor/blob/main/packages/react-doctor/src/utils/detect-user-lint-config.ts) (lines 7-33), it recognizes [`.oxlintrc.json`](https://github.com/millionco/react-doctor/blob/main/.oxlintrc.json), [`.eslintrc.json`](https://github.com/millionco/react-doctor/blob/main/.eslintrc.json), and other supported formats, stopping at a project boundary marked by `.git` or a monorepo root.

```typescript
// 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`](https://github.com/millionco/react-doctor/blob/main/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`](https://github.com/millionco/react-doctor/blob/main/packages/react-doctor/src/utils/run-oxlint.ts) (lines 41-55) constructs a temporary [`oxlintrc.json`](https://github.com/millionco/react-doctor/blob/main/oxlintrc.json). When adoption is enabled, it injects the filtered user config paths into the `"extends"` field alongside the React-Doctor plugin.

```json
{
  "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`](https://github.com/millionco/react-doctor/blob/main/react-doctor.config.json) to ignore existing lint configs:

```jsonc
{
  "adoptExistingLintConfig": false
}

```

**Result:** React-Doctor will not search for [`.eslintrc.json`](https://github.com/millionco/react-doctor/blob/main/.eslintrc.json) or [`.oxlintrc.json`](https://github.com/millionco/react-doctor/blob/main/.oxlintrc.json) files, scanning only with built-in rules.

### Enabling Adoption (Default)

Omit the key or explicitly set it to `true`:

```jsonc
{
  // 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:

```bash
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`](https://github.com/millionco/react-doctor/blob/main/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`](https://github.com/millionco/react-doctor/blob/main/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`](https://github.com/millionco/react-doctor/blob/main/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`](https://github.com/millionco/react-doctor/blob/main/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`](https://github.com/millionco/react-doctor/blob/main/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`](https://github.com/millionco/react-doctor/blob/main/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.