Node.js API

Use the Node API when you want to run React Doctor from another script or service.

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

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

console.log(result.score); // { score: 82, label: "Great" } or null
console.log(result.diagnostics); // Diagnostic[]
console.log(result.project); // detected framework, React version, etc.
console.log(result.reactDetected); // false means the scan targeted no React runtime

Diagnose options

diagnose accepts a second options object:

const result = await diagnose("./path/to/your/react-project", {
  lint: true,
});

Scan multiple projects

Pass diagnose an object with projects to scan several projects in one call. Use this for monorepos where each module needs its own score:

const result = await diagnose({
  projects: [
    { directory: "./modules/billing" },
    {
      directory: "./modules/payroll",
      config: { rules: { "react-doctor/no-danger": "off" } },
    },
  ],
  config: { ignore: { files: ["**/generated/**"] } },
  concurrency: 4,
});

console.log(result.score); // worst score across projects, or null
console.log(result.projects); // ProjectResult[], same order as input
console.log(result.diagnostics); // all diagnostics across projects

Projects run through a worker pool. concurrency caps how many scan at once (default 4); set it to 1 for sequential runs. Results keep input order.

Each entry in result.projects is either { ok: true, directory, ...DiagnoseResult } or { ok: false, directory, error }, so one failing project does not reject the whole batch.

Config layers additively, least to most specific: the project's on-disk doctor.config.*, then the batch-level config, then the per-project config. rules and categories merge per key, and ignore lists union, so a per-project override changes individual rules without discarding the base config.

Project entries accept the same scan options as diagnose. Per-project values win over batch-level values.

The deprecated deadCode option remains for compatibility. Setting it to false disables the project-level duplicated JSX check. It does not disable explicitly enabled graph rules, lint-based complexity rules, or the rest of the Maintainability category. New integrations should leave it unset.

Treat reactDetected: false as a wrong scan target, not a clean result. React-runtime rules do not run when React or Preact cannot be resolved.

JSON reports

Convert a single-project result into the same schema-version 3 report used by --json:

import { diagnose, toJsonReport } from "react-doctor/api";

const result = await diagnose("./path/to/your/react-project");
const report = toJsonReport(result, {
  version: "1.0.0",
});

Summarize diagnostics by severity and category:

import { summarizeDiagnostics } from "react-doctor/api";

const counts = summarizeDiagnostics(result.diagnostics);

Exported types and helpers

react-doctor/api exports:

• diagnose
• defineConfig
• hasReactRuntime
• toJsonReport
• summarizeDiagnostics
• getDiffInfo
• filterSourceFiles
• clearCaches
• JsonReport
• JsonReportSummary
• JsonReportProjectEntry
• JsonReportMode
• buildJsonReport
• buildJsonReportError
• typed project-discovery errors and isReactDoctorError

Call clearCaches() in a long-running process after project files or configuration change. It clears React Doctor's memoized project, package, config, ignore, and minified-file data.

Use the CLI when you want terminal output, PR comments, or install flows. Use the API when you need to embed React Doctor in another tool.