React State Map

Instantly visualize how state flows through your React application.

React State Map analyzes your codebase and generates interactive diagrams showing exactly how state, props, and context flow between components. No runtime dependencies, no code changes required - just pure static analysis.

Installation

# Run directly with npx (no install required)
npx @react-state-map/cli ./src

# Or install globally
npm install -g @react-state-map/cli

Usage

# Analyze current directory, output to state-map.html
react-state-map

# Analyze specific directory
react-state-map ./src

# Custom output file
react-state-map ./src --output my-state-map.html

# Output as JSON (for programmatic use)
react-state-map ./src --format json --output state.json

# Watch mode - auto-regenerate on file changes
react-state-map ./src --watch

# Don't auto-open in browser
react-state-map ./src --no-open

# Set prop drilling threshold
react-state-map ./src --threshold 4

# Include/exclude patterns
react-state-map ./src --include "**/*.tsx" --exclude "**/test/**"

Options

| Option | Short | Default | Description | |--------|-------|---------|-------------| | --output <file> | -o | state-map.html | Output file path | | --format <format> | -f | html | Output format: html or json | | --watch | -w | false | Watch for file changes | | --threshold <n> | -t | 3 | Prop drilling threshold (hops) | | --no-open | | false | Don't open output in browser | | --include <patterns> | -i | **/*.tsx,**/*.jsx | Glob patterns to include | | --exclude <patterns> | -e | node_modules,... | Glob patterns to exclude |

What It Detects

State Types

| State Type | Detection | |------------|-----------| | useState | Variable name, initial value | | useReducer | Reducer name, initial state | | useContext | Context name, provider/consumer | | Redux | useSelector, useDispatch | | Zustand | useStore, useXxxStore patterns | | Custom Hooks | Any useXxx hook calls |

Visualization Features

• ELK.js Layout Engine: Hierarchical graph layout with optimized edge crossing minimization
• Cytoscape.js Canvas Rendering: GPU-accelerated rendering for smooth performance with large graphs
• Semantic Zoom: Directory overview at far zoom, full component detail up close
• Fuzzy Search: Find components by name, file path, or props with real-time results
• Path Finding: Find shortest path between any two components
• Edge Layer Controls: Toggle Props, Context, Hierarchy, and Drilling edges independently
• Focus Mode: Isolate a component and its direct neighbors
• State Flow: See which components own state and how it propagates
• Context Boundaries: Visualize React Context providers with color-coded boundaries
• Collapsible Subtrees: Click to collapse/expand component subtrees
• Prop Drilling Detection: Automatically detect props passed through too many layers

Anti-Pattern Detection

| Badge | Detection | Description | |-------|-----------|-------------| | N drilling | Prop Drilling | Props passed through 3+ components without being used | | N passthrough | Pass-Through Components | Components that only forward props without consuming them | | N bundles | Large Prop Bundles | Object props with 5+ properties being passed through | | N leaks | Context Leaks | useContext values extracted and re-passed as props | | N renames | Prop Renames | Props renamed 2+ times through destructuring |

Output

HTML (default)

Generates a standalone, interactive HTML file with:

• Blue nodes = Components with local state
• Green nodes = Stateless components
• Green arrows = Props flow
• Purple dashed arrows = Context flow
• Directory groups = Semantic zoom shows directory overview when zoomed out
• Purple boundaries = Context provider scope
• Layers panel = Toggle edge types (Props, Context, Hierarchy, Drilling)
• Search bar = Fuzzy search for components
• Path button = Find shortest path between two components
• ▼/▶ indicators = Collapsible nodes
• Red highlights = Prop drilling paths
• Role badges = consumer / passthrough / transformer / mixed

Pan, zoom, search, find paths, toggle layers, collapse/expand nodes, click components for details, and switch between views.

JSON

{
  "components": [...],
  "edges": [...],
  "contexts": [...],
  "stats": {
    "totalComponents": 42,
    "statefulComponents": 12,
    "propDrillingPaths": 3
  }
}

Use Cases

| Challenge | Solution | |-----------|----------| | "Where does this prop come from?" | Visual trace from source to destination | | "Which components use this context?" | Context boundary visualization | | "Is this prop drilling?" | Automatic detection with hop count | | "What state does this component have?" | Click any node to see details | | CI/CD documentation | Generate HTML reports automatically | | Code reviews | Share state flow visualizations |

VS Code Extension

For real-time visualization while coding, use the VS Code extension.

Requirements

• Node.js 18.0.0 or higher
• React project with .tsx or .jsx files

License

MIT

Feedback & Issues

Open an issue on GitHub