React Mapper

A comprehensive React component dependency analyzer that maps relationships, detects anti-patterns, and provides actionable insights for improving your codebase architecture.

Features

Core Analysis

• Dependency Graph - Maps parent-child relationships between all React components
• God Component Detection - Identifies components with too many responsibilities
• Coupling Analysis - Detects tightly coupled components that are hard to maintain
• Prop Drilling Detection - Tracks props passed through multiple component layers

Extended Analysis

• Circular Dependencies - Finds import cycles that cause bundling issues
• Unused Components - Detects components that are never rendered
• Complexity Scoring - Calculates cognitive complexity for each component
• Custom Hook Analysis - Maps hook dependencies and identifies patterns
• Render Cascade Analysis - Identifies components that trigger unnecessary re-renders
• TypeScript Props - Extracts prop types from TypeScript interfaces
• Performance Hints - Detects inline objects, missing deps, memo candidates
• Accessibility Patterns - Checks for common a11y issues
• Bundle Impact - Estimates component contribution to bundle size
• Test Coverage Mapping - Maps components to their test files

Export Formats

• Interactive HTML - D3.js force-directed graph with search and filtering
• Mermaid Diagrams - For embedding in markdown documentation
• GraphViz DOT - For generating publication-quality diagrams
• SVG Export - Standalone vector diagrams
• Dependency Matrix - Heatmap showing component relationships
• JSON - Machine-readable output for custom tooling

CI/CD Integration

• Threshold Enforcement - Fail builds when metrics exceed limits
• Historical Tracking - Track architecture health over time
• Snapshot Comparison - Compare current state against baselines
• Badge Generation - Shields.io badges for README

Developer Experience

• Interactive TUI - Terminal UI with keyboard navigation
• Watch Mode - Re-analyze on file changes
• Component Search - Find components by name or path
• Refactor Suggestions - Actionable recommendations for improvement

Installation

# Clone and install
git clone <repo-url>
cd react-mapper
npm install

# Link for global usage
npm link

# Or run directly
node bin/react-mapper.js <path-to-react-project>

Usage

Basic Analysis

# Analyze current directory
react-mapper .

# Analyze specific project
react-mapper /path/to/react-app

# Non-interactive mode (stdout output)
react-mapper ./my-app --no-interactive

Output Formats

# Summary (default)
react-mapper ./my-app -o summary

# JSON for tooling
react-mapper ./my-app -o json --export analysis.json

# Component tree
react-mapper ./my-app -o tree

# Mermaid diagram
react-mapper ./my-app -o mermaid --export graph.md

# GraphViz DOT
react-mapper ./my-app -o graphviz --export graph.dot

# Interactive HTML report
react-mapper ./my-app -o html --export report.html

# Dependency matrix heatmap
react-mapper ./my-app -o matrix --export matrix.html

# SVG diagram
react-mapper ./my-app -o svg --export diagram.svg

Extended Analysis

# Run all analysis types
react-mapper ./my-app --all-analysis

# Individual analysis flags
react-mapper ./my-app --cycles          # Circular dependencies
react-mapper ./my-app --unused          # Unused components
react-mapper ./my-app --complexity      # Complexity scores
react-mapper ./my-app --performance     # Performance hints
react-mapper ./my-app --a11y            # Accessibility issues
react-mapper ./my-app --bundle          # Bundle impact
react-mapper ./my-app --coverage        # Test coverage
react-mapper ./my-app --refactor        # Refactor suggestions

# Combine multiple
react-mapper ./my-app --cycles --unused --complexity

Impact Analysis

# See what's affected if you change a component
react-mapper ./my-app --impact Button

# Search for components
react-mapper ./my-app --search "Modal"

CI/CD Integration

# CI mode - exits with code 1 if thresholds exceeded
react-mapper ./my-app --ci

# Custom thresholds
react-mapper ./my-app --ci \
  --max-god-score 50 \
  --max-coupling 50 \
  --max-drilling 3 \
  --min-health 80

# Save snapshot and check thresholds
react-mapper ./my-app --ci --save "pr-123"

Historical Tracking

# Save analysis snapshot
react-mapper ./my-app --save "v1.0-release"

# View history
react-mapper ./my-app --history

# Compare with baseline
react-mapper ./my-app --compare "v1.0-release"

Watch Mode

# Re-analyze on file changes
react-mapper ./my-app --watch

Badge Generation

# Generate shields.io badge markdown
react-mapper ./my-app --badge

# Generate standalone SVG badge
react-mapper ./my-app --badge-svg --export health-badge.svg

Understanding the Metrics

God Component Score (0-100+)

Components with too many responsibilities. Score based on:

• Fan-out (children count) × 10
• Props count × 3
• Hooks count × 5
• State connections × 8

Threshold: Score > 60 indicates a god component

Coupling Score (0-100+)

How tightly connected a component is:

• Fan-in (parents) × 5
• Fan-out (children) × 5
• Shared props bonus

Threshold: Score > 60 indicates high coupling

Prop Drilling Depth

How many layers a prop passes through unchanged.

Threshold: Depth >= 4 suggests using Context or state management

Health Score (0-100%)

Overall architecture health:

• Penalized by god components (×2 weight)
• Penalized by high coupling
• Penalized by deep prop drilling

Threshold: 70%+ = Healthy, 50-69% = Needs attention, <50% = Critical

Interactive Mode

The interactive terminal UI provides:

1. Tree View - Navigate the component hierarchy with expand/collapse
2. Metrics Panel - Sortable table of component metrics
3. Warnings Panel - All issues grouped by severity
4. Summary Panel - Project overview with health score

Keyboard Shortcuts

• Tab / 1-4: Switch views
• j/k or arrows: Navigate
• Enter / Space: Expand/collapse (tree view)
• s: Change sort (metrics view)
• q: Quit

CLI Options

Options:
  -V, --version          Output version number
  -i, --interactive      Launch interactive terminal UI (default: true)
  --no-interactive       Output to stdout instead
  -o, --output <format>  Output format: summary, json, tree, mermaid, graphviz,
                         html, matrix, svg (default: "summary")
  --export <file>        Export to file
  --patterns <patterns>  Glob patterns to scan (comma-separated)
  --ignore <patterns>    Patterns to ignore (comma-separated)
  --cycles               Detect circular dependencies
  --unused               Detect unused components
  --complexity           Analyze component complexity
  --performance          Show performance hints
  --a11y                 Check accessibility patterns
  --bundle               Estimate bundle impact
  --coverage             Map test coverage
  --refactor             Show refactor suggestions
  --all-analysis         Run all analysis types
  --impact <component>   Show impact analysis for specific component
  --search <query>       Search/filter components
  --ci                   CI mode: check thresholds and exit with code
  --max-god-score <n>    Max god component score (default: 60)
  --max-coupling <n>     Max coupling score (default: 60)
  --max-drilling <n>     Max prop drilling depth (default: 4)
  --min-health <n>       Minimum health score (default: 70)
  --save [tag]           Save snapshot to history
  --history              Show analysis history
  --compare <ref>        Compare with previous snapshot
  -w, --watch            Watch mode: re-analyze on changes
  --badge                Generate README badge
  --badge-svg            Generate SVG badge
  -h, --help             Display help

CI Configuration Example

GitHub Actions

name: Architecture Check
on: [push, pull_request]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Check architecture
        run: |
          npx react-mapper . --ci \
            --max-god-score 60 \
            --min-health 70

      - name: Generate report
        if: always()
        run: npx react-mapper . -o html --export report.html --no-interactive

      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: architecture-report
          path: report.html

Requirements

• Node.js 18+
• React project with .js, .jsx, .ts, or .tsx components

License

MIT