Maintaining a component library means living with a specific kind of anxiety.

Not the obvious bugs — those get caught. It's the quiet ones: a useEffect that shouldn't exist, a re-render that compounds across ten consuming apps, an accessibility gap that slipped through because ESLint didn't have a rule for it.

That's the gap React Doctor fills.

What Is React Doctor?

React Doctor is a static analyzer built specifically for React and React Native codebases. One command scans your project and surfaces issues across:

• State and effect anti-patterns
• Performance regressions
• Accessibility risks
• Architecture smells
• Security concerns

It's not a replacement for ESLint — it's a second opinion that catches what ESLint misses.

Setup in a Monorepo

Adding it to our ui-kit-lib took about five minutes:

// package.json
{
  "scripts": {
    "doctor": "react-doctor"
  },
  "devDependencies": {
    "react-doctor": "0.2.5"
  }
}

For a monorepo with Storybook, generated output, and test artifacts, a scoped ignore config keeps the signal clean:

// react-doctor.config.json
{
  "ignore": {
    "files": [
      "**/dist/**",
      "**/storybook-static/**",
      "**/coverage/**",
      "**/.cache/**",
      "**/tmp/**"
    ]
  }
}

Without this, React Doctor scans build output and inflates the findings with noise.

What It Actually Caught

Our workspace includes UI components, primitives, icons, locale packages, and a Storybook app. Each package passes TypeScript, formatting, and linting — but that's not the same as being clean.

Here are two patterns it flagged that are easy to miss in review:

Inline array computation on every render:

// ❌ Runs filter on every render
const filteredItems = items.filter((item) => item.visible);
return <Select options={filteredItems} />;

// ✅ Stable reference, only recomputes when items changes
const filteredItems = useMemo(
  () => items.filter((item) => item.visible),
  [items]
);
return <Select options={filteredItems} />;

Derived state copied through useEffect:

// ❌ Extra render cycle, unnecessary sync
useEffect(() => {
  setActive(value);
}, [value]);

// ✅ Just read the prop directly during render
const active = value;

These patterns work. They compile, they test, they ship. But at component-library scale where one primitive gets consumed across an entire product they compound quietly.

After running React Doctor, we revisited and cleaned up real components including Accordion, Avatar, ComboBox, Modal, Select, SearchBox, Popper, and ThemeProvider.

How to Use It Effectively

1. Run it locally first

pnpm doctor

Don't panic if the count is high on the first run. Triage by category.

2. Fix high-signal issues first

Prioritize in this order:

• Errors before warnings
• Performance and re-render issues
• State/effect anti-patterns
• Accessibility findings

3. Add it to CI

npx react-doctor@latest install

Choose Yes when it prompts for GitHub Actions. From that point, every PR gets inline comments on the exact lines that introduced a regression — before merge, not after.

The Real Value

React Doctor won't replace code review or architectural judgment. What it does is shift the quality conversation earlier.

For a UI kit, that matters more than for most projects. Every component is a shared primitive. A fragile pattern in Select doesn't stay in Select it lives in every form across every app that consumes the library.

The shift React Doctor enabled for us:

Before: "This component works."

After: "This component is cleaner, safer, and less likely to regress."

That's the kind of improvement that compounds.

Try It

npx react-doctor@latest

No config needed to start. See what it finds on your codebase. If you maintain a design system, component library, or internal UI package, there's a good chance it surfaces something worth fixing.

Do you use any React-specific quality gates in your component library or monorepo? Curious what others are using — React Doctor, custom ESLint rules, Storybook interaction tests, visual regression, or something else.