Configuration

Configure React Doctor behavior with react-doctor.config.json

Configuration File

Create a react-doctor.config.json file in your project root to customize React Doctor’s behavior.

react-doctor.config.json

{
  "lint": true,
  "deadCode": true,
  "verbose": false,
  "diff": false,
  "failOn": "none",
  "ignore": {
    "rules": [],
    "files": []
  }
}

Configuration Options

Scan Options

lint · boolean · default: "true"

Enable or disable linting checks using oxlint.

deadCode · boolean · default: "true"

Enable or disable dead code detection using Knip.

verbose · boolean · default: "false"

Show file details and line numbers for each diagnostic.

Example:

{
  "lint": true,
  "deadCode": false,
  "verbose": true
}

Diff Mode

diff · boolean | string · default: "false"

Enable diff mode to scan only changed files.

• false: Disabled
• true: Auto-detect changes
• "branch-name": Compare against specific branch (e.g., "main")

Examples:

Disabled

{
  "diff": false
}

Auto-detect

{
  "diff": true
}

Specific Branch

{
  "diff": "main"
}

Error Handling

failOn · 'error' | 'warning' | 'none' · default: "none"

Control when React Doctor exits with an error code.

• "error": Exit with code 1 only if errors are found
• "warning": Exit with code 1 if any warnings or errors are found
• "none": Never exit with error code

Example:

{
  "failOn": "error"
}

Use "failOn": "error" in CI to fail builds on errors while allowing warnings.

Ignore Configuration

ignore · object

Configure rules and files to ignore during scanning.

ignore.rules · string[] · default: "[]"

Array of rule identifiers to ignore. Format: "plugin/rule-name"

ignore.files · string[] · default: "[]"

Array of glob patterns for files to ignore.

Example:

{
  "ignore": {
    "rules": [
      "react-doctor/no-array-index-key",
      "oxlint/no-unused-vars"
    ],
    "files": [
      "**/*.test.tsx",
      "**/tests/**",
      "src/legacy/**"
    ]
  }
}

Complete Configuration Example

react-doctor.config.json

{
  "lint": true,
  "deadCode": true,
  "verbose": false,
  "diff": "main",
  "failOn": "error",
  "ignore": {
    "rules": [
      "react-doctor/no-array-index-key"
    ],
    "files": [
      "**/*.test.tsx",
      "**/*.stories.tsx",
      "src/generated/**",
      "dist/**",
      "build/**"
    ]
  }
}

Configuration Priority

React Doctor resolves configuration in the following order (highest to lowest priority):

1. CLI flags: Explicit command-line options
2. Configuration file: react-doctor.config.json
3. Defaults: Built-in default values

Example:

# CLI flag overrides config file
npx react-doctor --no-lint

Even if react-doctor.config.json has "lint": true, the --no-lint flag takes precedence.

TypeScript Support

For TypeScript projects, you can use type definitions for better autocomplete:

react-doctor.config.json

{
  "$schema": "https://react.doctor/schema.json",
  "lint": true,
  "deadCode": true,
  "verbose": false,
  "failOn": "error"
}

Finding Rule Names

To find rule names for the ignore.rules array:

1. Run React Doctor with --verbose flag:

   npx react-doctor --verbose
   

2. Look for the rule identifier in the output:

   ✗ useEffect dependencies array is missing dependencies
     Rule: react-doctor/exhaustive-deps
   

3. Add to your config:

   {
     "ignore": {
       "rules": ["react-doctor/exhaustive-deps"]
     }
   }
   

Common Patterns

CI Configuration

{
  "lint": true,
  "deadCode": true,
  "verbose": true,
  "failOn": "error",
  "ignore": {
    "files": [
      "**/*.test.tsx",
      "**/__mocks__/**"
    ]
  }
}

{
  "lint": true,
  "deadCode": false,
  "verbose": false,
  "diff": "main",
  "failOn": "none"
}

{
  "lint": true,
  "deadCode": true,
  "verbose": true,
  "failOn": "warning",
  "ignore": {
    "files": [
      "dist/**",
      "build/**"
    ]
  }
}

{
  "lint": true,
  "deadCode": false,
  "verbose": false
}

Validation

React Doctor validates the configuration file on load. Invalid configurations will show an error:

Error: Invalid configuration in react-doctor.config.json
  - failOn must be one of: "error", "warning", "none"
  - ignore.files must be an array of strings

Location

Place react-doctor.config.json in:

• Project root (same directory as package.json)
• Workspace root for monorepos

For monorepos, each workspace can have its own configuration file that overrides the root configuration.