React Complexity Audit

A comprehensive tool to analyze React component complexity and generate detailed reports. Helps identify components that need refactoring and provides actionable insights.

Features

• 📊 Complexity Scoring: Analyzes hooks, state management, effects, callbacks, and business logic
• 📈 Detailed Reports: Generates JSON, CSV, and interactive HTML reports
• 🔍 Pattern Analysis: Deep dive into component patterns and refactoring suggestions
• 🎯 Customizable: Configure scan directories, exclusions, and output paths
• 🚀 NPX Ready: Run directly without installation

Installation

Global Installation

npm install -g react-complexity-audit

NPX (No Installation Required)

npx react-complexity-audit

Usage

Basic Usage

# Analyze current directory
npx react-complexity-audit

# Or if installed globally
react-complexity-audit

Advanced Options

# Scan specific directory
npx react-complexity-audit --dir ./src

# Specify output directory
npx react-complexity-audit --output ./reports

# Run pattern analysis on top 10 complex components
npx react-complexity-audit --pattern-deep

# Limit analysis to first N files (useful for testing)
npx react-complexity-audit --limit 100

# Custom exclude patterns
npx react-complexity-audit --exclude "node_modules,dist,build,.next,custom-folder"

# Include .js files (default: .ts/.tsx only)
npx react-complexity-audit --include-js

# Combine options
npx react-complexity-audit --dir ./src --output ./reports --pattern-deep
npx react-complexity-audit --dir ./src --include-js --pattern-deep

Help

npx react-complexity-audit --help

Output

The tool generates multiple report formats in the output directory:

1. component-complexity-report.html

Interactive HTML report with:

• Summary statistics
• Clickable component list
• Detailed metrics for each component
• Complexity score breakdown
• Visual complexity ratings

2. component-complexity-report.json

Detailed JSON data with all metrics for programmatic access

3. component-complexity-report.csv

Spreadsheet-compatible CSV format with:

• Component name and path
• Complexity score and rating
• Line count
• Hook counts
• Effect counts
• Custom hooks
• Business logic complexity

4. summary-stats.json

High-level statistics:

• Total components analyzed
• Average complexity
• High complexity component count
• Top 10 most complex components

5. pattern-analysis.json (with --pattern-deep)

Detailed pattern analysis for top 10 complex components

Complexity Scoring

The complexity score is calculated based on:

• useState hooks: ×2 points each
• useEffect hooks: ×3 points each
• useCallback/useMemo: ×2 points each
• useReducer: ×3 points each
• Custom hooks: ×2 points each
• Complex dependencies: ×2 points each
• State variables: ×2 points each
• Complex state: ×3 points each
• Callbacks: ×0.8 points each
• Event handlers: ×1.2 points each
• Conditional rendering: ×1 point each
• Iterations (.map, .filter, etc.): ×1.5 points each
• Nested iterations: ×4 points each (heavy penalty)
• Complex conditionals: ×2 points each
• Complex destructuring: ×1 point each

Complexity Ratings

• Simple: < 10 points
• Moderate: 10-25 points
• Complex: 25-50 points
• Very Complex: > 50 points

Examples

Example 1: Analyze entire project

cd /path/to/react-project
npx react-complexity-audit

Reports will be generated in ./react-complexity-audit-report

Example 2: Analyze specific directory with custom output

npx react-complexity-audit --dir ./src/components --output ./analysis

Example 3: Deep analysis with pattern detection

npx react-complexity-audit --pattern-deep --output ./detailed-report

Requirements

• Node.js >= 14.0.0
• React project with TypeScript/JavaScript components

File Exclusions

By default, the tool excludes:

• node_modules
• dist
• build
• .next
• .rush
• rush-logs
• __tests__
• .test. files
• .stories. files
• coverage

You can customize these with the --exclude option.

Supported File Types

By default:

• .ts (TypeScript)
• .tsx (TypeScript React)

With --include-js flag:

• .js (JavaScript)
• .jsx (JavaScript React)

Test and story files are automatically excluded from the main analysis (.test.ts, .test.tsx, .test.js, .test.jsx, .stories.tsx, .stories.jsx).

Tips for Interpreting Results

1. High Complexity Components: Components with scores > 50 are candidates for refactoring
2. Many Hooks: More than 15 hooks suggests the component might be doing too much
3. Deep JSX Nesting: More than 8 levels of nesting indicates need for sub-components
4. Complex Effects: Effects with > 3 dependencies should be reviewed
5. Many Props: Components with > 8 props might benefit from prop grouping

Refactoring Suggestions

When you identify complex components, consider:

1. Extract Custom Hooks: Move state and effect logic to custom hooks
2. Split Components: Break large components into smaller, focused ones
3. Reduce Props: Use composition or context for deeply nested props
4. Simplify Effects: Separate concerns into individual effects
5. Extract Business Logic: Move complex calculations outside the component

License

ISC