React Doctor: A Deterministic Code Scanner for Your React Apps

You know that feeling when you inherit a React codebase and have no idea where the state bugs, performance hogs, or security holes are? Or when you're shipping to production and want to catch issues before they become user-facing problems? React Doctor aims to help with that — by scanning your React codebase deterministically for state, performance, and security issues.

It's not a linter. It's not a runtime debugger. It's a static analysis tool that actually understands React patterns, and it might just save you a few headaches.

What It Does

React Doctor scans your entire React codebase and identifies:

• State issues — bad state patterns, stale closures, incorrect useState or useReducer usage, missing dependencies in hooks
• Performance issues — unnecessary re-renders, missing React.memo, components that update too often, expensive computations in render
• Security issues — XSS vectors in JSX, unsafe dangerouslySetInnerHTML usage, exposed API keys or secrets in the codebase

The key word here is deterministic. Unlike some tools that rely on heuristics or runtime profiling, React Doctor gives you the same results every time on the same code. No false positives that randomly appear. No flaky tests.

Why It's Cool

Most static analysis tools for React are either too generic (looking for broad patterns) or too specific (just checking for one thing). React Doctor actually understands React semantics:

• It knows that useEffect with [count] means something different than useEffect with []
• It can spot when you're modifying state directly instead of using the setter
• It catches the classic "callback inside an effect without deps" pattern that leads to stale closures
• It flags JSX patterns that could lead to XSS, like rendering unsanitized user input

The output is also nice — you get a clear list of issues with file paths, line numbers, and descriptions that actually make sense. No walls of cryptic error codes.

How to Try It

Clone the repo and give it a spin:

git clone https://github.com/millionco/react-doctor.git
cd react-doctor
npm install
npx react-doctor scan ./src

Or if you just want to see what it does on a sample project, the repo has example apps in the examples/ folder. Point it at one of those and watch it find bugs.

npx react-doctor scan ./examples/state-bugs

No configuration needed. Just point it at a directory with React code and it'll tell you what it finds.

Final Thoughts

Is this going to replace your linter, your type checker, or your manual code review? No. But it's a solid addition to your toolkit, especially if you're dealing with a large or unfamiliar codebase. It catches the kind of subtle React-specific issues that generic tools miss — and it does it deterministically, so you can trust the results.

If you maintain a React project, especially one that's shipped to production, running React Doctor before deploys seems like a no-brainer. Low effort, potentially high reward.

Found via @githubprojects