React Doctor - diagnostyka i analiza jakości kodu React

React Doctor - kompletny przewodnik po diagnostyce kodu React

Twój projekt React działa, ale czy jest zdrowy?

Każdy programista React zna ten moment. Projekt rośnie, kolejne komponenty dochodzą, a Ty nie jesteś pewien, czy pod maską nie czają się problemy z wydajnością, martwy kod albo luki bezpieczeństwa. Code review pomaga, ale nie wyłapie wszystkiego. Lintery sprawdzają składnię, ale nie architekturę. Czego brakuje? Narzędzia, które spojrzy na projekt holistycznie i powie wprost: "Twoja aplikacja jest zdrowa w 78%" - a potem wskaże, co konkretnie naprawić.

Dokładnie do tego służy React Doctor.

Czym jest React Doctor?

React Doctor to narzędzie do analizy kodu React, stworzone przez zespół Million.js. Działa jak lekarz dla Twojego projektu - skanuje kod źródłowy, przeprowadza dwa równoległe przebiegi analizy (linting i wykrywanie martwego kodu) i generuje wynik zdrowotny w skali 0-100. Do tego daje konkretne diagnostyki z dokładnymi ścieżkami plików, numerami linii i poziomami istotności.

Narzędzie automatycznie wykrywa framework (Next.js, Vite, Remix), wersję Reacta i konfigurację kompilatora. Nie wymaga skomplikowanej konfiguracji - jedno polecenie w terminalu wystarczy, żeby uzyskać pełny obraz kondycji projektu.

Dlaczego React Doctor?

Kompleksowa analiza w jednym narzędziu

Zamiast konfigurować osobno ESLint z dziesiątkami pluginów, narzędzie do wykrywania martwego kodu i analizator bundla, React Doctor łączy to wszystko. Sprawdza ponad 60 reguł w ośmiu kategoriach:

Wynik zdrowotny zamiast listy błędów

Większość linterów zwraca surową listę ostrzeżeń i błędów. React Doctor przetwarza je w zrozumiały wynik:

• 75-100 - Projekt w dobrej kondycji
• 50-74 - Wymaga poprawek
• 0-49 - Stan krytyczny

Błędy mają większą wagę niż ostrzeżenia, więc wynik odzwierciedla faktyczny wpływ problemów na jakość kodu.

Automatyczne rozpoznawanie frameworka

React Doctor sam wykrywa, czy pracujesz z Next.js, Vite czy Remix. Dostosowuje zestaw reguł do frameworka, wersji Reacta i tego, czy używasz React Compiler. Nie musisz ręcznie konfigurować profilu analizy.

Instalacja i pierwsze użycie

Szybki start

Nie musisz niczego instalować globalnie. Wystarczy jedno polecenie:

npx -y react-doctor@latest .

To wszystko. React Doctor pobierze się automatycznie, przeskanuje bieżący katalog i wyświetli raport z wynikiem zdrowotnym.

Tryb szczegółowy

Jeśli chcesz widzieć konkretne pliki i linie przy każdej regule:

npx -y react-doctor@latest . --verbose

Tylko wynik

W skryptach CI/CD często potrzebujesz samego wyniku liczbowego:

npx -y react-doctor@latest . --score

Opcje CLI

React Doctor oferuje zestaw flag, które pozwalają dostosować analizę:

npx -y react-doctor@latest . --no-lint

Pomija sprawdzanie reguł lintingu i wykonuje tylko wykrywanie martwego kodu.

npx -y react-doctor@latest . --no-dead-code

Pomija wykrywanie martwego kodu i wykonuje tylko linting.

npx -y react-doctor@latest . --diff main

Skanuje tylko zmienione pliki w porównaniu z gałęzią main. Idealne do sprawdzania pull requestów.

npx -y react-doctor@latest . --fix

Otwiera Ami (asystenta AI od Million.js), który automatycznie naprawia znalezione problemy.

npx -y react-doctor@latest . --project dashboard

W monorepo skanuje tylko wybrany projekt workspace.

Konfiguracja

Plik konfiguracyjny

Utwórz react-doctor.config.json w katalogu głównym projektu:

{
  "ignore": {
    "rules": ["react/no-danger", "jsx-a11y/no-autofocus"],
    "files": ["src/generated/**", "src/**/*.test.tsx"]
  }
}

Opcje konfiguracji

Konfiguracja w package.json

Alternatywnie możesz dodać konfigurację do package.json w kluczu reactDoctor:

{
  "name": "my-react-app",
  "reactDoctor": {
    "ignore": {
      "rules": ["react/no-danger"],
      "files": ["src/generated/**"]
    },
    "verbose": true
  }
}

Jeśli istnieją oba pliki, react-doctor.config.json ma priorytet.

Node.js API

React Doctor udostępnia programistyczny interfejs, który pozwala na integrację z własnymi narzędziami:

import { diagnose } from "react-doctor/api"

const result = await diagnose("./path/to/react-project")

console.log(result.score)
console.log(result.diagnostics)
console.log(result.project)

Obiekt wynikowy

Funkcja diagnose zwraca obiekt z trzema głównymi polami:

interface DiagnoseResult {
  score: {
    score: number
    label: string
  } | null
  diagnostics: Diagnostic[]
  project: {
    framework: string
    reactVersion: string
  }
}

interface Diagnostic {
  filePath: string
  plugin: string
  rule: string
  severity: "error" | "warning"
  message: string
  help: string
  line: number
  column: number
  category: string
}

Opcjonalne parametry

Możesz kontrolować, które analizy mają być uruchomione:

const result = await diagnose(".", {
  lint: true,
  deadCode: false
})

Przykład integracji z własnym dashboardem

import { diagnose } from "react-doctor/api"

async function generateReport() {
  const result = await diagnose(".")

  if (!result.score) {
    console.log("Za mało danych do oceny")
    return
  }

  const errors = result.diagnostics.filter(d => d.severity === "error")
  const warnings = result.diagnostics.filter(d => d.severity === "warning")

  const report = {
    score: result.score.score,
    label: result.score.label,
    framework: result.project.framework,
    errorCount: errors.length,
    warningCount: warnings.length,
    topIssues: errors.slice(0, 5).map(d => ({
      file: d.filePath,
      rule: d.rule,
      message: d.message,
      line: d.line
    }))
  }

  return report
}

Integracja z GitHub Actions

React Doctor ma oficjalną GitHub Action, która pozwala na automatyczne skanowanie pull requestów:

name: React Doctor
on:
  pull_request:
    branches: [main]

jobs:
  diagnose:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0

      - uses: millionco/react-doctor@main
        with:
          diff: main
          github-token: ${{ secrets.GITHUB_TOKEN }}

Parametry akcji

Wykorzystanie wyniku w pipeline

Akcja zwraca wynik jako output score, który można wykorzystać w kolejnych krokach:

jobs:
  diagnose:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0

      - uses: millionco/react-doctor@main
        id: doctor
        with:
          diff: main
          github-token: ${{ secrets.GITHUB_TOKEN }}

      - name: Check score
        run: |
          if [ "${{ steps.doctor.outputs.score }}" -lt "70" ]; then
            echo "Score too low: ${{ steps.doctor.outputs.score }}"
            exit 1
          fi

Integracja z agentami kodującymi

React Doctor oferuje zestaw reguł, które można zainstalować w popularnych agentach AI:

curl -fsSL https://react.doctor/install-skill.sh | bash

Obsługiwani agenci:

• Cursor
• Claude Code
• Amp Code
• Codex
• Gemini CLI
• OpenCode
• Windsurf
• Antigravity

Po instalacji agent zyskuje dostęp do 47+ reguł React best practices i może automatycznie stosować je podczas generowania kodu.

Benchmarki znanych projektów open source

React Doctor był używany do analizy popularnych projektów React. Wyniki pokazują, że nawet duże, utrzymywane projekty mają pole do poprawy:

Warto zauważyć, że nawet projekty z wynikiem 62-64 to dojrzałe, produkcyjne aplikacje. Wynik React Doctora nie oznacza, że kod jest zły - wskazuje obszary, w których można go ulepszyć.

Porównanie z innymi narzędziami

Praktyczne scenariusze użycia

Audyt istniejącego projektu

Przejmujesz projekt od innego zespołu i chcesz szybko ocenić jego jakość:

npx -y react-doctor@latest . --verbose

W kilka sekund dostajesz pełen obraz: wynik zdrowotny, listę problemów posortowaną według istotności i wskazówki, od czego zacząć naprawy.

Code review w CI/CD

Dodajesz GitHub Action i każdy pull request automatycznie dostaje komentarz z diagnostyką. Możesz ustawić próg (np. 70 punktów), poniżej którego merge jest blokowany.

Monitorowanie jakości w czasie

Zapisujesz wynik z każdego builda i śledzisz trend. Jeśli wynik spada, wiesz, że trzeba poświęcić sprint na porządki.

Skanowanie zmian w PR

Zamiast analizować cały projekt za każdym razem, skanujesz tylko zmienione pliki:

npx -y react-doctor@latest . --diff main

To znacznie szybsze i skupia uwagę na tym, co faktycznie się zmieniło.

Najczęściej zadawane pytania

Czy React Doctor wymaga instalacji? Nie. Wystarczy uruchomić npx -y react-doctor@latest . i narzędzie pobierze się automatycznie. Nie musisz dodawać go do zależności projektu, chyba że chcesz używać Node.js API.

Czy działa z Next.js / Vite / Remix? Tak. React Doctor automatycznie wykrywa framework i dostosowuje zestaw reguł. Nie musisz nic konfigurować.

Czy mogę wyłączyć konkretne reguły? Tak. Użyj pliku react-doctor.config.json z sekcją ignore.rules lub klucza reactDoctor w package.json.

Czy wynik null oznacza błąd? Nie. Wynik null pojawia się, gdy w projekcie jest zbyt mało kodu React do oceny. To nie jest błąd - po prostu narzędzie potrzebuje wystarczającej ilości danych.

Czy React Doctor wysyła mój kod gdziekolwiek? Nie. Analiza odbywa się lokalnie na Twojej maszynie. Kod nie jest wysyłany na żadne serwery.

Czy mogę używać go w monorepo? Tak. Użyj flagi --project, aby wskazać konkretne projekty workspace do skanowania.

Podsumowanie

React Doctor wypełnia lukę między prostymi linterami a rozbudowanymi platformami do analizy kodu. Daje szybki, zrozumiały obraz kondycji projektu React bez konieczności konfiguracji. Sprawdza 60+ reguł w ośmiu kategoriach, automatycznie rozpoznaje framework i generuje wynik zdrowotny 0-100.

Narzędzie najlepiej sprawdza się w trzech scenariuszach: szybki audyt projektu, automatyczne sprawdzanie pull requestów przez GitHub Actions i monitorowanie jakości kodu w czasie. Dzięki Node.js API można je zintegrować z dowolnym narzędziem wewnętrznym.

Jest darmowe, open source (licencja MIT) i nie wymaga wysyłania kodu na zewnętrzne serwery. Jedno polecenie npx i masz pełną diagnostykę.

React Doctor - a complete guide to React code diagnostics

Your React project works, but is it healthy?

Every React developer knows this feeling. The project grows, new components pile up, and you're not sure if there are performance issues hiding under the hood, dead code lurking in forgotten files, or security vulnerabilities waiting to be exploited. Code review helps, but it doesn't catch everything. Linters check syntax, but not architecture. What's missing? A tool that looks at your project holistically and says plainly: "Your app is 78% healthy" - and then points out exactly what to fix.

That's exactly what React Doctor does.

What is React Doctor?

React Doctor is a code analysis tool for React projects, created by the Million.js team. It works like a doctor for your project - it scans the source code, runs two parallel analysis passes (linting and dead code detection), and generates a health score on a 0-100 scale. On top of that, it provides concrete diagnostics with exact file paths, line numbers, and severity levels.

The tool automatically detects your framework (Next.js, Vite, Remix), React version, and compiler configuration. It doesn't require complex setup - a single terminal command is enough to get a full picture of your project's health.

Why React Doctor?

Comprehensive analysis in a single tool

Instead of configuring ESLint separately with dozens of plugins, a dead code detection tool, and a bundle analyzer, React Doctor combines all of this. It checks over 60 rules across eight categories:

A health score instead of a list of errors

Most linters return a raw list of warnings and errors. React Doctor processes them into an understandable score:

• 75-100 - Project is in good shape
• 50-74 - Needs work
• 0-49 - Critical condition

Errors carry more weight than warnings, so the score reflects the actual impact of issues on code quality.

Automatic framework detection

React Doctor automatically detects whether you're working with Next.js, Vite, or Remix. It adapts its rule set to your framework, React version, and whether you're using React Compiler. You don't need to manually configure an analysis profile.

Installation and first use

Quick start

You don't need to install anything globally. A single command is enough:

npx -y react-doctor@latest .

That's it. React Doctor will download automatically, scan the current directory, and display a report with the health score.

Verbose mode

If you want to see specific files and lines for each rule:

npx -y react-doctor@latest . --verbose

Score only

In CI/CD scripts you often need just the numeric score:

npx -y react-doctor@latest . --score

CLI options

React Doctor provides a set of flags that let you customize the analysis:

npx -y react-doctor@latest . --no-lint

Skips linting rules and runs only dead code detection.

npx -y react-doctor@latest . --no-dead-code

Skips dead code detection and runs only linting.

npx -y react-doctor@latest . --diff main

Scans only changed files compared to the main branch. Ideal for checking pull requests.

npx -y react-doctor@latest . --fix

Opens Ami (Million.js's AI assistant) which automatically fixes the detected issues.

npx -y react-doctor@latest . --project dashboard

In a monorepo, scans only the selected workspace project.

Configuration

Configuration file

Create react-doctor.config.json in your project root:

{
  "ignore": {
    "rules": ["react/no-danger", "jsx-a11y/no-autofocus"],
    "files": ["src/generated/**", "src/**/*.test.tsx"]
  }
}

Configuration options

Configuration in package.json

Alternatively, you can add the configuration to package.json under the reactDoctor key:

{
  "name": "my-react-app",
  "reactDoctor": {
    "ignore": {
      "rules": ["react/no-danger"],
      "files": ["src/generated/**"]
    },
    "verbose": true
  }
}

If both files exist, react-doctor.config.json takes precedence.

Node.js API

React Doctor exposes a programmatic interface that enables integration with your own tools:

import { diagnose } from "react-doctor/api"

const result = await diagnose("./path/to/react-project")

console.log(result.score)
console.log(result.diagnostics)
console.log(result.project)

Result object

The diagnose function returns an object with three main fields:

interface DiagnoseResult {
  score: {
    score: number
    label: string
  } | null
  diagnostics: Diagnostic[]
  project: {
    framework: string
    reactVersion: string
  }
}

interface Diagnostic {
  filePath: string
  plugin: string
  rule: string
  severity: "error" | "warning"
  message: string
  help: string
  line: number
  column: number
  category: string
}

Optional parameters

You can control which analyses are run:

const result = await diagnose(".", {
  lint: true,
  deadCode: false
})

Example integration with a custom dashboard

import { diagnose } from "react-doctor/api"

async function generateReport() {
  const result = await diagnose(".")

  if (!result.score) {
    console.log("Not enough data to evaluate")
    return
  }

  const errors = result.diagnostics.filter(d => d.severity === "error")
  const warnings = result.diagnostics.filter(d => d.severity === "warning")

  const report = {
    score: result.score.score,
    label: result.score.label,
    framework: result.project.framework,
    errorCount: errors.length,
    warningCount: warnings.length,
    topIssues: errors.slice(0, 5).map(d => ({
      file: d.filePath,
      rule: d.rule,
      message: d.message,
      line: d.line
    }))
  }

  return report
}

GitHub Actions integration

React Doctor has an official GitHub Action that enables automatic scanning of pull requests:

name: React Doctor
on:
  pull_request:
    branches: [main]

jobs:
  diagnose:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0

      - uses: millionco/react-doctor@main
        with:
          diff: main
          github-token: ${{ secrets.GITHUB_TOKEN }}

Action parameters

Using the score in a pipeline

The action returns the score as a score output, which can be used in subsequent steps:

jobs:
  diagnose:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0

      - uses: millionco/react-doctor@main
        id: doctor
        with:
          diff: main
          github-token: ${{ secrets.GITHUB_TOKEN }}

      - name: Check score
        run: |
          if [ "${{ steps.doctor.outputs.score }}" -lt "70" ]; then
            echo "Score too low: ${{ steps.doctor.outputs.score }}"
            exit 1
          fi

Integration with coding agents

React Doctor offers a rule set that can be installed in popular AI coding agents:

curl -fsSL https://react.doctor/install-skill.sh | bash

Supported agents:

• Cursor
• Claude Code
• Amp Code
• Codex
• Gemini CLI
• OpenCode
• Windsurf
• Antigravity

After installation, the agent gains access to 47+ React best practice rules and can automatically apply them when generating code.

Benchmarks of well-known open source projects

React Doctor has been used to analyze popular React projects. The results show that even large, well-maintained projects have room for improvement:

It's worth noting that even projects scoring 62-64 are mature, production-ready applications. A React Doctor score doesn't mean the code is bad - it points to areas where it can be improved.

Comparison with other tools

Practical use cases

Auditing an existing project

You're taking over a project from another team and want to quickly assess its quality:

npx -y react-doctor@latest . --verbose

Within seconds you get the full picture: health score, a list of issues sorted by severity, and guidance on where to start fixing.

Code review in CI/CD

Add the GitHub Action and every pull request automatically gets a comment with diagnostics. You can set a threshold (e.g., 70 points) below which merging is blocked.

Monitoring quality over time

Save the score from each build and track the trend. If the score drops, you know it's time to dedicate a sprint to cleanup.

Scanning PR changes

Instead of analyzing the entire project every time, scan only the changed files:

npx -y react-doctor@latest . --diff main

This is much faster and focuses attention on what actually changed.

Frequently asked questions

Does React Doctor require installation? No. Just run npx -y react-doctor@latest . and the tool will download automatically. You don't need to add it to your project's dependencies unless you want to use the Node.js API.

Does it work with Next.js / Vite / Remix? Yes. React Doctor automatically detects your framework and adjusts the rule set. You don't need to configure anything.

Can I disable specific rules? Yes. Use a react-doctor.config.json file with the ignore.rules section or the reactDoctor key in package.json.

Does a null score mean an error? No. A null score appears when there's not enough React code in the project to evaluate. It's not an error - the tool simply needs sufficient data to generate a score.

Does React Doctor send my code anywhere? No. The analysis runs locally on your machine. Code is not sent to any servers.

Can I use it in a monorepo? Yes. Use the --project flag to specify which workspace projects to scan.

Summary

React Doctor fills the gap between simple linters and complex code analysis platforms. It provides a quick, understandable picture of a React project's health without requiring configuration. It checks 60+ rules across eight categories, automatically detects your framework, and generates a 0-100 health score.

The tool works best in three scenarios: quick project audits, automatic pull request checking via GitHub Actions, and monitoring code quality over time. Thanks to the Node.js API, it can be integrated with any internal tool.

It's free, open source (MIT license), and doesn't require sending code to external servers. One npx command and you have full diagnostics.