react-state-basis

Runtime Architectural Auditor for React

Basis tracks when state updates (never what) to catch architectural debt that standard tools miss, while keeping your data private.

---

Quick Start

1. Install

npm i react-state-basis

2. Setup (Vite)

Add the plugin to your vite.config.ts. The Babel plugin auto-labels your hooks—you continue importing from react as normal.

import { basis } from 'react-state-basis/vite';

export default defineConfig({
  plugins: [
    react({ 
      babel: { plugins: [['react-state-basis/plugin']] } 
    }),
    basis()
  ]
});

3. Initialize

import { BasisProvider } from 'react-state-basis';

root.render(
  <BasisProvider 
    debug={true}
    showHUD={true} // Set to false for console-only forensics
  >
    <App />
  </BasisProvider>
);

4. Verify the Signal

Drop this pattern into any component. Basis will identify the rhythm of the debt within ~100ms.

const [a, setA] = useState(0);
const [b, setB] = useState(0);

useEffect(() => {
  setB(a + 1); // ⚡ BASIS: "Double Render Detected"
}, [a]);

return <button onClick={() => setA(a + 1)}>Pulse Basis</button>;

Click the button. You should see this in your console:

⚡ BASIS | DOUBLE RENDER
📍 Location: YourComponent.tsx
Issue: effect_L5 triggers b in a separate frame.
Fix: Derive b during the render phase (remove effect) or wrap in useMemo.

---

5. Control & Scope

• Ghost Mode: Disable the Matrix UI while keeping console-based forensics active by setting showHUD={false} on the provider.
• Selective Auditing: Add // @basis-ignore at the top of any file to disable instrumentation. Recommended for:
  • High-frequency animation logic (>60fps)
  • Third-party library wrappers
  • Intentional synchronization (e.g., local mirrors of external caches)

---

Visual Proof

The optional HUD shows your State Basis Matrix in real-time. Purple pulses ($\Omega$) are Context anchors; Red pulses (!) are redundant shadows.

Note: While the HUD visualizes real-time updates, the Architectural Health Report (Console) provides the deep topological analysis.

---

What Basis Detects

Basis uses Graph Theory, Signal Processing, and Linear Algebra to identify architectural violations that static linters miss:

• ⚡ Double Renders (Sync Leaks) - Detects when a useEffect triggers a state update immediately after a render, forcing the browser to paint twice.
• ⚡ Prime Movers (Root Causes) - Ignores downstream symptoms and points you to the exact hook or event that started the chain reaction.
• ⚡ Fragmented Updates - Detects when a single click forces updates in multiple different files/contexts simultaneously (Tearing risk).
• Ω Context Mirroring - Detects when you redundanty copy Global Context data into Local State (creating two sources of truth).
• ♊ Duplicate State - Identifies variables that always update at the exact same time and should be merged (e.g. isLoading + isSuccess).
• 🛑 Infinite Loops - A safety circuit-breaker that kills the auditor before a recursive update freezes your browser.

See examples & fixes →

---

Reports & Telemetry

Architectural Health Report

Check your entire app's state architecture by running window.printBasisReport() in the console.

• Refactor Priorities: Uses Spectral Influence (Eigenvector Centrality) to rank bugs by their systemic impact. It tells you what to fix first.
• Efficiency Score: A calculated percentage of how "clean" your architecture is (Sources of Truth - Causal Leaks).
• Sync Issues: Groups entangled variables into clusters (e.g., Boolean Explosions).

Hardware Telemetry

Verify engine efficiency and heap stability in real-time via window.getBasisMetrics().

---

Real-World Evidence

Basis is verified against industry-standard codebases to ensure high-fidelity detection:

• Excalidraw (114k⭐) - Caught a theme-sync leak forcing a double-render on every toggle. PR #10637
• shadcn-admin (10k⭐) - Detected redundant state pattern in viewport detection hooks. PR #274 (MERGED)

---

Integrations

Zustand

Wrap your store with basisLogger to give Basis visibility into external store updates. Store signals appear as Σ in the HUD and health report.

import { create } from 'zustand';
import { basisLogger } from 'react-state-basis/zustand';

export const useStore = create(
  basisLogger((set) => ({
    theme: 'light',
    toggleTheme: () => set((state) => ({ 
      theme: state.theme === 'light' ? 'dark' : 'light' 
    })),
  }), 'MyStore')
);

This enables detection of Store Mirroring, Store Sync Leaks, and Global Event Fragmentation across React and Zustand state simultaneously.

See full Zustand example →

More integrations coming

Planned: XState, React Qery, Redux Toolkit. Community PRs welcome.

---

Performance & Privacy

Development: <1ms overhead per update cycle, zero heap growth
Production: ~0.01ms per hook (monitoring disabled, ~2-3KB bundle)
Privacy: Only tracks update timing, never state values

See benchmarks →

---

Documentation & Theory

Basis is built on heuristics inspired by Signal Processing, Linear Algebra, and Graph Theory. To understand the underlying math, visit the Full Wiki.

---

Roadmap

Each era of Basis answers a different architectural question:

✓ v0.4.x - The Correlation Era - Are these states moving together?
✓ v0.5.x - The Decomposition Era - Is this local state just a copy of Context?
→ v0.6.x - The Graph Era - Which bug should I fix first for maximum impact?
v0.7.x - The Information Era - Does this state carry real information, or is it derivative?
v0.8.x - The Manifold Era - How many hooks does your component actually need?

More info

---

Built by LP • MIT License