The millionco/react-doctor repository provides a comprehensive tool for analyzing and improving the quality of React codebases. Its primary purpose is to detect and report bad React practices, offering actionable diagnostics and a health score ranging from 0 to 100. This score reflects the overall quality of the code, with 75+ considered great, 50–74 indicating the need for improvement, and below 50 deemed critical. React Doctor is compatible with popular frameworks such as Next.js, Vite, and React Native, making it versatile for modern React projects.
The tool is designed for ease of use, requiring only a single command to scan a project. It identifies issues across various domains, including state and effects management, performance, architecture, security, accessibility, and dead code. The rules it applies are context-aware, automatically adjusting based on the detected framework and React version. For developers using coding agents like Claude Code, Cursor, Codex, and OpenCode, React Doctor can be installed to teach these agents best practices, preventing the generation of poor-quality code.
Integration with continuous integration (CI) systems is straightforward. React Doctor ships with a composite GitHub Action, allowing teams to automate code health checks on pull requests and pushes. The action posts findings as PR comments and exposes the health score as an output, which can be used in subsequent workflow steps. Inputs such as directory, verbosity, project selection, diff base, GitHub token, and failure thresholds provide granular control over the action's behavior. Alternatively, the tool can be run directly via npx in CI scripts.
Configuration is highly flexible. Users can create a react-doctor.config.json file or use the reactDoctor key in package.json to customize rule and file exclusions, overrides, and surface controls. The ignore settings allow silencing specific rules globally, suppressing all rules for certain files, or applying targeted overrides for particular files and rules. Surface controls enable tuning diagnostics for different outputs, such as CLI, PR comments, score calculation, and CI failure gates, ensuring that only relevant issues are surfaced in each context.
React Doctor respects common ignore files and inline suppression comments, merging with existing lint configurations from oxlint or ESLint if present. It supports optional companion plugins like eslint-plugin-react-hooks and eslint-plugin-react-you-might-not-need-an-effect, enhancing its rule set when these are installed. Inline suppressions can be applied using comments, with detailed explanations available for why a rule fired or a suppression failed.
The tool is available as both a standalone CLI and as lint plugins for oxlint and ESLint, allowing integration into existing linting workflows. The CLI offers a range of options, including verbose output, JSON reporting, diff and staged modes for scanning only changed or staged files, and offline operation for CI environments. The scoring formula penalizes unique error and warning rules, encouraging teams to address root causes rather than individual instances.
React Doctor is particularly adept at handling mixed monorepos with both web and React Native packages, applying rules contextually based on package declarations and file extensions. It also provides specialized handling for platform-specific code, ensuring accurate diagnostics in cross-platform projects. Overall, React Doctor is a robust solution for maintaining high-quality React code, integrating seamlessly with modern development workflows and offering deep configurability for teams of all sizes.
