v0.6.2 — React & Next.js supported

Understand your
state management

Static analysis for Frontend codebases. Detect patterns, measure complexity, and catch anti-patterns across 11 state management libraries.

npm install -g state-analyzer
Get Started View on GitHub
state-analyzer analyze ./src 
Starting state analysis...

=== Analysis Summary ===

Total components: 68
Components with state: 12 (17.6%)
Total state usage: 20
Average: 1.7 states/component
Custom hooks: 30

Usage by type:
  useState: 16
  Zustand: 4

=== Complexity ===

Project grade: A (score: 1.1)

Component grades:
  A ████████████████████ (64)
  B ██ (2)
  C ██ (2)

=== Suggestions ===

  ! ToastProvider (src/contexts/ToastContext.tsx)
    4 state hooks detected — consider extracting to a custom hook

Features

🔍

11 Library Support

React hooks, Redux, Zustand, Jotai, MobX, Recoil, Valtio, TanStack Query, SWR — all detected automatically.

⚡

Custom Hook Analysis

Detects custom hook definitions and traces what state management patterns they use internally.

🏆

Complexity Scoring

A~F grade per component and project-wide. Use --threshold as a CI gate.

⚠

Anti-pattern Detection

Warns about unused state, excessive hooks, library mixing, and useContext overuse.

📊

Multiple Output Formats

Terminal, Markdown tables, Mermaid diagrams, and JSON export for CI pipelines.

🔌

Plugin System

Register custom state patterns for internal libraries via .stateanalyzerrc.json.

Supported Libraries

React Hooks
Redux
Zustand
Jotai
MobX
Recoil
Valtio
TanStack Query
SWR
+ Plugins

Usage

Install

npm install -g state-analyzer
# or yarn global add state-analyzer

Initialize

state-analyzer init

Analyze

state-analyzer analyze ./src

CI Gate

state-analyzer analyze ./src --threshold C

Markdown Report

state-analyzer analyze ./src --format md

Mermaid Diagram

state-analyzer analyze ./src --mermaid

Diff Mode

state-analyzer diff before.json after.json

Watch Mode

state-analyzer watch ./src

Options

state-analyzer analyze <path>

OptionAliasDescription
<path>-Directory to analyze (required)
--output <file>-oSave results as JSON
--verbose-vShow detailed component information
--threshold <grade>-tFail if project complexity exceeds grade (A/B/C/D/F)
--format <type>-fOutput format: default, md (markdown)
--mermaid-Output Mermaid diagram

state-analyzer diff <before> <after>

Compare two analysis JSON files and show added/removed/changed components, type deltas, and complexity changes.

state-analyzer watch <path>

Watch for file changes and re-analyze automatically with debounced updates.

state-analyzer init

Generate a .stateanalyzerrc.json config file with sensible defaults.

Configuration

Create a .stateanalyzerrc.json in your project root:

.stateanalyzerrc.json 
{
  "exclude": ["legacy/", "generated/"],
  "threshold": "C",
  "format": "default",
  "plugins": [
    {
      "name": "legend-state",
      "patterns": [{ "regex": "useObservable\\s*\\(", "type": "legend-state" }],
      "label": "Legend State"
    }
  ]
}
exclude File path patterns to skip during analysis
threshold Default complexity threshold grade
format Default output format (default, md)
plugins Custom state patterns for internal/third-party libraries

JSON Export

analysis.json 
{
  "summary": {
    "totalComponents": 68,
    "totalStateUsages": 20,
    "byType": { "useState": 16, "zustand": 4 },
    "complexity": { "averageScore": 1.1, "grade": "A" }
  },
  "components": [ ... ],
  "customHooks": [ ... ],
  "suggestions": [ ... ]
}