Skip to main content

​
Function Signature

export const diagnose = async (
  directory: string,
  options: DiagnoseOptions = {},
): Promise<DiagnoseResult>
The diagnose() function is the primary programmatic API for React Doctor. It analyzes a React codebase and returns diagnostics, score, and project information.

​
Parameters

​
directory
string
required
Absolute or relative path to the project directory to scan.
​
options
DiagnoseOptions
default:"{}"
Configuration options for the diagnosis.

​
Return Value

​
DiagnoseResult
object
The result of the diagnosis operation.

​
Errors

The function throws an error if:
  • No React dependency is found in package.json
  • The directory path is invalid or inaccessible
if (!projectInfo.reactVersion) {
  throw new Error("No React dependency found in package.json");
}

​
Examples

​
Basic usage

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

const result = await diagnose('./my-app');

console.log(`Found ${result.diagnostics.length} issues`);
console.log(`Score: ${result.score?.score}`);
console.log(`Completed in ${result.elapsedMilliseconds}ms`);

​
With options

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

const result = await diagnose('./my-app', {
  lint: true,
  deadCode: false,
});

for (const diagnostic of result.diagnostics) {
  console.log(`${diagnostic.severity}: ${diagnostic.message}`);
  console.log(`  at ${diagnostic.filePath}:${diagnostic.line}:${diagnostic.column}`);
}

​
Diff mode (scan specific files)

import { diagnose, getDiffInfo, filterSourceFiles } from 'react-doctor/api';

// Get changed files from git
const diffInfo = getDiffInfo('./my-app');
const changedFiles = diffInfo ? filterSourceFiles(diffInfo.changedFiles) : [];

// Scan only changed files
const result = await diagnose('./my-app', {
  includePaths: changedFiles,
});

console.log(`Scanned ${changedFiles.length} changed files`);
console.log(`Found ${result.diagnostics.length} issues in changes`);

​
Error handling

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

try {
  const result = await diagnose('./my-app');
  
  if (result.diagnostics.some(d => d.severity === 'error')) {
    console.error('Critical errors found!');
    process.exit(1);
  }
} catch (error) {
  console.error('Diagnosis failed:', error.message);
  process.exit(1);
}

​
CI integration

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

const result = await diagnose(process.cwd(), {
  lint: true,
  deadCode: true,
});

const errorCount = result.diagnostics.filter(d => d.severity === 'error').length;
const warningCount = result.diagnostics.filter(d => d.severity === 'warning').length;

console.log(`Errors: ${errorCount}, Warnings: ${warningCount}`);
console.log(`Score: ${result.score?.score} (${result.score?.label})`);

if (errorCount > 0) {
  process.exit(1);
}

​
Configuration File

The diagnose() function automatically loads configuration from react-doctor.config.json in the project directory. Options passed to the function take precedence over config file settings. See Configuration for more details.

Build docs developers (and LLMs) love

Get started for freeTalk to us