TypeScript Types

Core Types

Diagnostic

Represents a single diagnostic issue found in the codebase.

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

filePath

string

Absolute path to the file containing the issue.

plugin

string

Source of the diagnostic (e.g., "oxlint", "knip").

rule

string

Specific rule that was violated (e.g., "react-hooks/exhaustive-deps").

severity

'error' | 'warning'

Severity level of the issue.

message

string

Human-readable description of the issue.

help

string

Additional context or guidance for fixing the issue.

line

number

Line number where the issue occurs (1-indexed).

column

number

Column number where the issue occurs (1-indexed).

ProjectInfo

Information about the analyzed React project.

export interface ProjectInfo {
  rootDirectory: string;
  projectName: string;
  reactVersion: string | null;
  framework: Framework;
  hasTypeScript: boolean;
  hasReactCompiler: boolean;
  sourceFileCount: number;
}

rootDirectory

string

Absolute path to the project root directory.

projectName

string

Name of the project from package.json.

reactVersion

string | null

Version of React installed, or null if not found.

framework

Framework

Detected framework. See Framework type.

hasTypeScript

boolean

Whether TypeScript is detected in the project.

hasReactCompiler

boolean

Whether React Compiler (babel-plugin-react-compiler) is detected.

sourceFileCount

number

Total number of source files in the project.

ScoreResult

Overall health score for the codebase.

export interface ScoreResult {
  score: number;
  label: string;
}

score

number

Numeric score from 0-100, where 100 is perfect health.

label

string

Human-readable label for the score (e.g., "Excellent", "Good", "Fair", "Poor").

DiffInfo

Information about changed files in a git repository.

export interface DiffInfo {
  currentBranch: string;
  baseBranch: string;
  changedFiles: string[];
  isCurrentChanges?: boolean;
}

currentBranch

string

Name of the current git branch.

baseBranch

string

Name of the base branch for comparison.

changedFiles

string[]

Array of file paths that have changed.

isCurrentChanges

boolean

Whether the changes are uncommitted (working directory changes).

ReactDoctorConfig

Configuration object from react-doctor.config.json.

export interface ReactDoctorConfig {
  ignore?: ReactDoctorIgnoreConfig;
  lint?: boolean;
  deadCode?: boolean;
  verbose?: boolean;
  diff?: boolean | string;
  failOn?: FailOnLevel;
}

ignore

ReactDoctorIgnoreConfig

Rules and files to ignore. See ReactDoctorIgnoreConfig.

lint

boolean

Enable linting checks.

deadCode

boolean

Enable dead code detection.

verbose

boolean

Show verbose output with file details.

diff

boolean | string

Enable diff mode. If a string, specifies the base branch name.

failOn

FailOnLevel

Exit code behavior. See FailOnLevel.

ReactDoctorIgnoreConfig

Configuration for ignoring specific rules or files.

export interface ReactDoctorIgnoreConfig {
  rules?: string[];
  files?: string[];
}

rules

string[]

Array of rule IDs to ignore (e.g., ["react-hooks/exhaustive-deps"]).

files

string[]

Array of file glob patterns to ignore (e.g., ["**/*.test.tsx"]).

Enums & Unions

Framework

Supported React frameworks.

export type Framework =
  | "nextjs"
  | "vite"
  | "cra"
  | "remix"
  | "gatsby"
  | "expo"
  | "react-native"
  | "unknown";

nextjs

Framework

Next.js framework

vite

Framework

Vite framework

cra

Framework

Create React App

remix

Framework

Remix framework

gatsby

Framework

Gatsby framework

expo

Framework

Expo framework

react-native

Framework

React Native (non-Expo)

unknown

Framework

Framework could not be detected

FailOnLevel

Exit code behavior based on diagnostic severity.

export type FailOnLevel = "error" | "warning" | "none";

error

FailOnLevel

Exit with code 1 only if errors are found.

warning

FailOnLevel

Exit with code 1 if any warnings or errors are found.

none

FailOnLevel

Always exit with code 0 regardless of diagnostics.

Internal Types

These types are used internally by React Doctor but may be useful for advanced use cases.

EstimatedScoreResult

Estimated score improvement after fixing issues.

export interface EstimatedScoreResult {
  currentScore: number;
  currentLabel: string;
  estimatedScore: number;
  estimatedLabel: string;
}

ScanOptions

Internal options used by the CLI scanner.

export interface ScanOptions {
  lint?: boolean;
  deadCode?: boolean;
  verbose?: boolean;
  scoreOnly?: boolean;
  offline?: boolean;
  includePaths?: string[];
}

ScanResult

Internal result from the scanner.

export interface ScanResult {
  diagnostics: Diagnostic[];
  scoreResult: ScoreResult | null;
  skippedChecks: string[];
}

PackageJson

Structure of a package.json file.

export interface PackageJson {
  name?: string;
  dependencies?: Record<string, string>;
  devDependencies?: Record<string, string>;
  peerDependencies?: Record<string, string>;
  workspaces?: string[] | { packages: string[] };
}

WorkspacePackage

Information about a workspace package in a monorepo.

export interface WorkspacePackage {
  name: string;
  directory: string;
}

Utility Functions

getDiffInfo()

Returns information about changed files in a git repository.

export function getDiffInfo(
  directory: string,
  baseBranch?: string
): DiffInfo | null

filterSourceFiles()

Filters an array of file paths to include only source files.

export function filterSourceFiles(files: string[]): string[]

files

string[]

required

Array of file paths to filter.

Returns: string[] - Array containing only source files (JavaScript, TypeScript, JSX, TSX).

Examples

Type-safe diagnostic handling

import type { Diagnostic } from 'react-doctor/api';

function groupDiagnosticsBySeverity(diagnostics: Diagnostic[]) {
  const errors = diagnostics.filter(d => d.severity === 'error');
  const warnings = diagnostics.filter(d => d.severity === 'warning');
  
  return { errors, warnings };
}

Custom score display

import type { ScoreResult } from 'react-doctor/api';

function formatScore(score: ScoreResult | null): string {
  if (!score) return 'N/A';
  
  const emoji = score.score >= 90 ? '🟢' :
                score.score >= 70 ? '🟡' :
                score.score >= 50 ? '🟠' : '🔴';
  
  return `${emoji} ${score.score}/100 (${score.label})`;
}

Working with project info

import type { ProjectInfo, Framework } from 'react-doctor/api';

function getFrameworkDisplayName(framework: Framework): string {
  const names: Record<Framework, string> = {
    nextjs: 'Next.js',
    vite: 'Vite',
    cra: 'Create React App',
    remix: 'Remix',
    gatsby: 'Gatsby',
    expo: 'Expo',
    'react-native': 'React Native',
    unknown: 'Unknown',
  };
  
  return names[framework];
}

function displayProjectInfo(project: ProjectInfo) {
  console.log(`Project: ${project.projectName}`);
  console.log(`Framework: ${getFrameworkDisplayName(project.framework)}`);
  console.log(`React: ${project.reactVersion || 'Not found'}`);
  console.log(`TypeScript: ${project.hasTypeScript ? 'Yes' : 'No'}`);
  console.log(`Files: ${project.sourceFileCount}`);
}

CLI

Node.js API

Core Types

Diagnostic

ProjectInfo

ScoreResult

DiffInfo

ReactDoctorConfig

ReactDoctorIgnoreConfig

Enums & Unions

Framework

FailOnLevel

Internal Types

EstimatedScoreResult

ScanOptions

ScanResult

PackageJson

WorkspacePackage

Utility Functions

getDiffInfo()

filterSourceFiles()

Examples

Type-safe diagnostic handling

Custom score display

Working with project info

Build docs developers (and LLMs) love

CLI

Node.js API

​Core Types

​Diagnostic

​ProjectInfo

​ScoreResult

​DiffInfo

​ReactDoctorConfig

​ReactDoctorIgnoreConfig

​Enums & Unions

​Framework

​FailOnLevel

​Internal Types

​EstimatedScoreResult

​ScanOptions

​ScanResult

​PackageJson

​WorkspacePackage

​Utility Functions

​getDiffInfo()

​filterSourceFiles()

​Examples

​Type-safe diagnostic handling

​Custom score display

​Working with project info

Build docs developers (and LLMs) love

Core Types

Diagnostic

ProjectInfo

ScoreResult

DiffInfo

ReactDoctorConfig

ReactDoctorIgnoreConfig

Enums & Unions

Framework

FailOnLevel

Internal Types

EstimatedScoreResult

ScanOptions

ScanResult

PackageJson

WorkspacePackage

Utility Functions

getDiffInfo()

filterSourceFiles()

Examples

Type-safe diagnostic handling

Custom score display

Working with project info