react-state-flow 0.0.3 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HoangSonDeveloper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,41 +1,79 @@
 # react-state-flow
 
-Visualize your React component hierarchy and state flow in real-time.
+Visualize React component state and re-render flow in real time.
 
-<!-- screenshot here -->
+Parses your React codebase into an interactive graph, then overlays live render data from your running app — so you can see which components re-render, how often, and how state flows through the tree.
 
-## Usage
+## How it works
+
+1. **Static analysis** — scans your source files and builds a component graph (components, contexts, parent-child relationships)
+2. **Runtime instrumentation** — hooks into React DevTools to capture render events without modifying your components
+3. **Live visualization** — renders an interactive graph in the browser, updated in real time as your app runs
 
-Run in any React project — no install required:
+## Installation
 
 ```bash
-npx react-state-flow ./src
+npm install react-state-flow
 ```
 
-A browser window opens at `http://localhost:7272` showing an interactive graph of your components, their relationships, and context providers.
+## Usage
+
+### Step 1 — Add runtime instrumentation
 
-The graph updates automatically when you save files.
+Import at the very top of your `main.tsx` (before React mounts):
 
-## Runtime instrumentation (optional)
+```ts
+import 'react-state-flow/runtime'
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import App from './App'
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>
+)
+```
 
-To see which components are re-rendering and how many times, add the runtime to your app:
+The runtime is automatically disabled in production (`NODE_ENV=production` or Vite's `MODE=production`), so this import is safe to commit.
+
+### Step 2 — Run the CLI
 
 ```bash
-npm install @rsf/runtime
+npx react-state-flow ./src
 ```
 
-```ts
-// main.tsx — must be the very first import
-import '@rsf/runtime'
+The browser opens automatically at `http://localhost:7272` with your component graph. Start your app and the graph updates live as components render.
+
+## CLI
+
+```bash
+react-state-flow [directory]
 ```
 
-Components that re-render will be highlighted in the graph in real-time.
+| Argument | Default | Description |
+|---|---|---|
+| `directory` | `.` | Path to your React source directory |
+
+The CLI runs on port `7272`. Your app's Vite dev server can run on any other port.
+
+## What the graph shows
+
+- **Component nodes** — each React function component, with its `useState`/`useReducer` state slots listed
+- **Context nodes** — each `createContext` call
+- **Parent-child edges** — JSX render relationships between components
+- **Context provision edges** — which component renders a `Context.Provider`
+- **Context subscription edges** — which components call `useContext`
+- **Render counts** — live badge on each node showing how many times it has rendered
+- **Render flash** — green highlight for 800ms after a component re-renders
+
+The graph updates automatically when you save source files (no restart needed).
 
 ## Requirements
 
-- Node 18+
-- React 17 or 18
+- Node.js 18+
+- React 16.8+ (hooks required for DevTools hook support)
 
-## How it works
+## License
 
-`react-state-flow` parses your source files statically using Babel to extract component relationships and context usage, then serves an interactive graph UI. The optional `@rsf/runtime` package hooks into React's internal fiber reconciler (the same mechanism used by React DevTools) to capture render events and stream them to the UI over WebSocket.
+MIT

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}