Skip to main content

​
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: 
{
  "diff": false
}

​
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

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

​
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us