Core Analysis¶

Core Issue: Adoption should be driven by tech stack, repo scale, and the need for static quality metrics.

Suitable Scenarios (Recommended)¶

• Medium-to-large React apps: Complex state/effect logic, multi-team collaboration, and PR workflows benefit from anti-pattern detection.
• Cross-platform projects: React Native + Web codebases gain from framework-aware rules to reduce cross-platform false positives.
• Teams wanting measurable health: Those wanting a 0–100 health metric in CI/PR to track code quality over time.
• Teams using/training coding agents: npx react-doctor install can embed best practices into code-generation agents.

Not Recommended (Avoid)¶

• Non-React projects: The rule set is React-focused and offers little value for Vue/Angular/back-end repos.
• Small or disposable repos: Maintenance and config cost may outweigh benefits.
• Restricted runtime environments: Repos that cannot run Node or install dependencies will struggle to integrate.

Practical Advice¶

1. Run npx -y react-doctor@latest . as a trial to inspect score and top rule violations.
2. Consider whether your team can maintain ignore lists and config—mid/large teams gain more.

Important: If your main issues are runtime-only, supplement static checks with tests and runtime monitoring.

Summary: Best for large React codebases needing semantic governance; not suitable as a primary tool in non-React or constrained environments.

Core Analysis¶

Core Issue: The biggest friction when adding a new static checker is noise from vendor/generated files and improper suppressions.

Technical Analysis¶

• Key capabilities:
• react-doctor.config.json supports ignore.rules, ignore.files, and ignore.overrides for fine-grained control.
• The tool respects .gitignore, .eslintignore, .oxlintignore and can merge existing lint configs (adoptExistingLintConfig).
• GitHub Action integration can post PR comments and expose scores for visibility rather than immediate failure.

Practical Recommendations (phased rollout)¶

1. Merge existing config: Enable adoptExistingLintConfig:true so react-doctor folds in current ESLint rules and avoids duplicate alerts.
2. Exclude vendor/generated files: Add src/generated/**, node_modules/** or build output to ignore.files; use ignore.overrides for file-specific exceptions.
3. Show, don’t block: Configure the Action to post comments (warnings) on PRs first, then escalate to fail-on progressively.
4. Use incremental scans: Use --diff/--staged for large repos to limit CI time and focus on changed files.
5. Debug suppressions: Run --explain when suppression annotations seem ineffective to correct annotation placement.

Important: Don’t flip all strict rules on in a large repo at once—converge gradually.

Summary: Merge lint configs, use fine-grained ignores, make PR feedback non-blocking initially, and use incremental scans to integrate react-doctor with minimal noise.

Core Analysis¶

Core Issue: Dead-code detection relies on static reachability analysis and has inherent blind spots with modern build and dynamic loading patterns.

Technical Analysis¶

• Accurate cases:
• Explicitly unused functions/variables/components not imported anywhere.
• Modules whose static reference graph is fully resolvable.
• Common false positives:
• Dynamic imports / code-splitting: Imports computed from strings or runtime values are not statically resolvable.
• Runtime registration/reflection: Frameworks/plugins registering components at runtime via conventions/metadata.
• Dependency injection or service locators: Symbols injected or referenced via reflection at runtime.
• Test/tooling references: Test runners or build tools referencing files only at runtime.

How to reduce false positives¶

1. Configure ignores: Add generated or runtime-registered directories to ignore.files (e.g., src/generated/**, plugins/**).
2. Explicit exports/annotations: Mark modules referenced at runtime with explicit exports or comments to aid static tooling or to be excluded.
3. Use overrides: Use ignore.overrides to allow specific files exceptions while keeping other rules active.
4. Prioritize diffs: Focus human review on changed files (--diff/--staged) to reduce noisy audits.

Important: Treat static dead-code detection as high-value but imperfect—great for explicit unused code, needing config for dynamic runtime patterns.

Summary: Reliable for most static cases; mitigate false positives in dynamic-loading or runtime-registration scenarios via config, annotations, and diff-first workflows.

Core Analysis¶

Core Issue: Injecting static rules and explainability into coding agents enables prevention at generation time and creates a feedback loop for continuous improvement.

Technical Analysis¶

• Built-in capability: npx react-doctor install can inject rules/guidance into many agents; the tool runs via CLI/Action/ESLint plugin and offers --explain to clarify rule triggers.
• Integration paths:
• Pre-generation: Seed agents’ prompts/templates with recommended rules, anti-pattern examples, and do/don’t lists.
• Post-generation: Run react-doctor immediately on generated output and feed diagnostics back to the agent to request fixes.
• CI gatekeeping: Use diff scans on agent PRs and post scores/comments as a quality gate or visibility metric.

Practical Recommendations¶

1. Add concise rule summaries to agent prompts (e.g., avoid side effects during render; prefer useMemo/useCallback only when needed).
2. Include react-doctor install in agent initialization so team rules are automatically applied.
3. Implement a post-generation hook to run react-doctor and return --explain details to the agent for correction.
4. Use --diff mode for agent-generated changes to minimize scan overhead.

Important: Agents must be able to receive injected rules and a feedback loop; otherwise you can only audit post-generation, not prevent errors at source.

Summary: A combined strategy—pre-populating prompts, automatic post-generation scans with feedback, and CI scoring—meaningfully reduces bad React code from agents and helps bake best practices into the generation pipeline.