@nhonh/react-debugger 1.0.0 → 1.0.1

package/README.md

@@ -1,67 +1,393 @@
-# ⚛️ React Debugger
+# ⚛️ React Debugger Extension
 
-Advanced debugging & performance optimization tool for ReactJS applications.
+[![npm version](https://img.shields.io/npm/v/@nhonh/react-debugger.svg)](https://www.npmjs.com/package/@nhonh/react-debugger)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Quick Install
+**Advanced debugging & performance optimization tool for ReactJS applications.**
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/hoainho/react-debugger-extension/main/docs/images/preview.png" alt="React Debugger Preview" width="800">
+</p>
+
+---
+
+## 🚀 Quick Install
+
+```bash
+npx @nhonh/react-debugger
+```
+
+Or install to a specific folder:
 
 ```bash
-npx react-debugger
+npx @nhonh/react-debugger ./my-extension
 ```
 
-This will download the Chrome extension to your local machine.
+---
+
+## 📦 What's Included
 
-## Usage
+| Tab | Purpose | Key Metrics |
+|-----|---------|-------------|
+| 📊 **Timeline** | Visual timeline of all React events | Renders, state changes, effects, errors |
+| 🎯 **UI & State** | Detect React anti-patterns | State mutations, missing/duplicate keys |
+| ⚡ **Performance** | Track component performance | Render count, duration, Core Web Vitals |
+| 💾 **Memory** | Monitor memory usage | Heap size, growth rate, leak detection |
+| 🔄 **Side Effects** | Analyze useEffect hooks | Missing cleanups, dependency issues |
+| 📐 **CLS** | Layout stability monitoring | Cumulative Layout Shift score |
+| 🗄️ **Redux** | Redux state debugging | State tree, action history |
 
-### Interactive Mode
+---
+
+## 🔧 Installation Guide
+
+### Step 1: Download the Extension
 
 ```bash
-npx react-debugger
+npx @nhonh/react-debugger
 ```
 
-Follow the prompts to choose installation directory.
+<p align="center">
+  <img src="https://raw.githubusercontent.com/hoainho/react-debugger-extension/main/docs/images/install-cli.png" alt="CLI Installation" width="600">
+</p>
 
-### Direct Install
+### Step 2: Load in Chrome
 
-```bash
-npx react-debugger ./my-extension
+1. Open Chrome → Navigate to `chrome://extensions/`
+2. Enable **Developer mode** (toggle top-right)
+3. Click **"Load unpacked"**
+4. Select your installation folder
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/hoainho/react-debugger-extension/main/docs/images/chrome-load.png" alt="Load Extension" width="600">
+</p>
+
+### Step 3: Start Debugging
+
+1. Open any React website
+2. Press `F12` to open DevTools
+3. Click the **"React Debugger"** tab
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/hoainho/react-debugger-extension/main/docs/images/devtools-tab.png" alt="DevTools Tab" width="600">
+</p>
+
+---
+
+## 📖 Quick Start Guide
+
+### Finding Performance Issues
+
+1. Open the **Performance** tab
+2. Look at "Top Re-rendering Components" table
+3. Components with high render counts need optimization
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/hoainho/react-debugger-extension/main/docs/images/performance-tab.png" alt="Performance Tab" width="600">
+</p>
+
+**What the render triggers mean:**
+
+| Trigger | Cause | Solution |
+|---------|-------|----------|
+| `props` | Parent passed new props | Use `React.memo()` |
+| `state` | Component's state changed | Reduce state updates |
+| `context` | Context value changed | Split into smaller contexts |
+| `parent` | Parent component re-rendered | Memoize this component |
+
+### Finding Code Issues
+
+1. Open the **UI & State** tab
+2. Issues are sorted by severity (Error → Warning → Info)
+3. Click any issue to see details and fix suggestions
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/hoainho/react-debugger-extension/main/docs/images/ui-state-tab.png" alt="UI & State Tab" width="600">
+</p>
+
+**Common issues detected:**
+
+```jsx
+// ❌ DIRECT_STATE_MUTATION
+const [items, setItems] = useState([]);
+items.push(newItem);  // Mutating directly!
+setItems(items);
+
+// ✅ Fixed
+setItems([...items, newItem]);
 ```
 
-### Options
+```jsx
+// ❌ INDEX_AS_KEY
+{items.map((item, i) => <li key={i}>{item}</li>)}
 
+// ✅ Fixed
+{items.map(item => <li key={item.id}>{item.name}</li>)}
 ```
--v, --version    Show version number
--h, --help       Show help
+
+### Detecting Memory Leaks
+
+1. Open the **Memory** tab
+2. Click **"Start Monitoring"**
+3. Use your app for a few minutes
+4. Check the **Growth Rate** - should be near 0 KB/s
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/hoainho/react-debugger-extension/main/docs/images/memory-tab.png" alt="Memory Tab" width="600">
+</p>
+
+**Memory health indicators:**
+
+| Usage | Status | Action |
+|-------|--------|--------|
+| < 70% | ✅ Healthy | No action needed |
+| 70-90% | ⚠️ Warning | Monitor closely |
+| > 90% | 🔴 Critical | Investigate immediately |
+
+### Using Timeline
+
+1. Open the **Timeline** tab
+2. Filter by event type (renders, state, effects, errors)
+3. Click any event to see related events highlighted
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/hoainho/react-debugger-extension/main/docs/images/timeline-tab.png" alt="Timeline Tab" width="600">
+</p>
+
+**Event types:**
+
+| Icon | Type | What it captures |
+|------|------|------------------|
+| 🔄 | Render | Component mounts and re-renders |
+| 📦 | State | useState and Redux state changes |
+| ⚡ | Effect | useEffect runs and cleanups |
+| ❌ | Error | JavaScript errors and crashes |
+| 🧠 | Memory | Memory usage snapshots |
+
+---
+
+### 🔄 Side Effects Tab
+
+Find issues with `useEffect` hooks that cause bugs and memory leaks.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/hoainho/react-debugger-extension/main/docs/images/side-effects-tab.png" alt="Side Effects Tab" width="600">
+</p>
+
+**Issues detected:**
+
+| Issue | Severity | Problem |
+|-------|----------|---------|
+| **MISSING_CLEANUP** | ⚠️ Warning | Effect doesn't clean up timers/listeners |
+| **MISSING_DEP** | ⚠️ Warning | Variable used but not in dependency array |
+| **INFINITE_LOOP_RISK** | 🔴 Error | Effect updates state it depends on |
+| **STALE_CLOSURE** | ⚠️ Warning | Callback captures outdated values |
+
+**Example fixes:**
+
+```jsx
+// ❌ Missing cleanup - causes memory leak
+useEffect(() => {
+  const id = setInterval(() => tick(), 1000);
+  // Timer keeps running after unmount!
+}, []);
+
+// ✅ With cleanup
+useEffect(() => {
+  const id = setInterval(() => tick(), 1000);
+  return () => clearInterval(id);  // Cleanup!
+}, []);
 ```
 
-## Loading the Extension in Chrome
+```jsx
+// ❌ Stale closure - always logs initial value
+useEffect(() => {
+  const handler = () => console.log(count);
+  window.addEventListener('click', handler);
+  return () => window.removeEventListener('click', handler);
+}, []);  // Missing count dependency!
 
-After installation:
+// ✅ Fixed - re-subscribe when count changes
+useEffect(() => {
+  const handler = () => console.log(count);
+  window.addEventListener('click', handler);
+  return () => window.removeEventListener('click', handler);
+}, [count]);
+```
 
-1. Open `chrome://extensions/` in Chrome
-2. Enable **Developer mode** (toggle in top right)
-3. Click **Load unpacked**
-4. Select the folder where you installed the extension
+---
 
-## Features
+### 📐 CLS Tab (Layout Stability)
 
-- 🎯 **UI & State Issues** - Detect direct state mutation, missing keys, index as key
-- ⚡ **Performance Analysis** - Track re-renders, identify excessive renders
-- 🔄 **Side Effects** - Find missing cleanup, dependency issues in useEffect
-- 📐 **CLS Monitor** - Track Cumulative Layout Shift in real-time
-- 🗄️ **Redux DevTools** - View state tree, dispatch actions manually
-- 📊 **Timeline** - Visual timeline of all React events
-- 💾 **Memory** - Monitor memory usage and detect leaks
+Monitor **Cumulative Layout Shift** - elements jumping around causes poor UX.
 
-## Requirements
+<p align="center">
+  <img src="https://raw.githubusercontent.com/hoainho/react-debugger-extension/main/docs/images/cls-tab.png" alt="CLS Tab" width="600">
+</p>
 
-- Node.js >= 18.0.0
-- Chrome, Brave, or any Chromium-based browser
+**CLS Score:**
+
+| Score | Rating | User Experience |
+|-------|--------|-----------------|
+| < 0.1 | ✅ Good | Stable, no jumps |
+| 0.1 - 0.25 | ⚠️ Needs Work | Noticeable shifts |
+| > 0.25 | 🔴 Poor | Frustrating, elements jump |
+
+**Common causes & fixes:**
+
+```jsx
+// ❌ Image without dimensions - causes shift when loaded
+<img src="photo.jpg" alt="Photo" />
+
+// ✅ With dimensions - space reserved
+<img src="photo.jpg" alt="Photo" width={800} height={600} />
+```
+
+```jsx
+// ❌ Dynamic content pushes things down
+{loaded && <Content />}
+
+// ✅ Reserve space while loading
+<div style={{ minHeight: 200 }}>
+  {loaded ? <Content /> : <Skeleton />}
+</div>
+```
 
-## Links
+**Top shift sources table** shows which elements cause the most shifts - fix those first!
+
+---
+
+## 🎯 Common Debugging Scenarios
+
+### "My app feels slow"
+
+```
+1. Performance tab → Check "Slowest Components"
+2. Look for render times > 16ms
+3. Enable "React Scan" to see re-renders visually
+4. Fix components with excessive renders
+```
+
+### "Memory keeps growing"
+
+```
+1. Memory tab → Start Monitoring
+2. Navigate around your app
+3. If growth rate stays positive → memory leak
+4. Side Effects tab → Check for missing cleanups
+```
+
+### "Layout jumps when loading"
+
+```
+1. CLS tab → See shift score
+2. Check "Top Shift Sources" table
+3. Add width/height to images
+4. Reserve space for dynamic content
+```
+
+### "Redux state is wrong"
+
+```
+1. Redux tab → Expand state tree
+2. Check Action History for unexpected actions
+3. Use Action Dispatcher to test
+```
+
+---
+
+## 🗄️ Redux DevTools (Powerful Feature!)
+
+The Redux tab provides a complete debugging experience:
+
+### Live State Editing
+
+**Click any value to edit it directly** - changes apply immediately!
+
+```
+State Tree:
+▼ user
+  ├─ name: "John"     ← Click to edit → "Jane" → Enter ✓
+  ├─ role: "user"     ← Click → "admin" → See UI change!
+  └─ balance: 100     ← Click → 0 → Test empty state
+```
+
+### Array Manipulation
+
+Reorder or delete array items with one click:
+
+```
+▼ cart.items: Array(3)
+  ├─ [0]: Book   [↑] [↓] [×]  ← Move up/down or delete
+  ├─ [1]: Pen    [↑] [↓] [×]
+  └─ [2]: Paper  [↑] [↓] [×]
+```
+
+### Action Dispatcher
+
+Test your reducers without writing code:
+
+```
+Type: cart/addItem
+Payload: { "productId": 123, "quantity": 2 }
+[Dispatch] → Watch state update instantly!
+```
+
+### Pro Tips
+
+| Scenario | Action |
+|----------|--------|
+| Test admin features | Edit `user.role` → "admin" |
+| Test empty states | Edit `posts` → `[]` |
+| Test error handling | Dispatch `api/error` action |
+| Test loading UI | Dispatch `fetch/pending` action |
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/hoainho/react-debugger-extension/main/docs/images/redux-tab.png" alt="Redux Tab" width="600">
+</p>
+
+---
+
+## ⌨️ CLI Options
+
+```bash
+npx @nhonh/react-debugger [destination] [options]
+
+Options:
+  -v, --version    Show version number
+  -h, --help       Show help
+
+Examples:
+  npx @nhonh/react-debugger              # Interactive mode
+  npx @nhonh/react-debugger ./extension  # Install to ./extension
+```
+
+---
+
+## 📚 Full Documentation
+
+- [Getting Started Guide](./docs/GETTING-STARTED.md) - Detailed setup instructions
+- [Understanding Each Tab](./docs/TABS-GUIDE.md) - Deep dive into all features
+- [Troubleshooting](./docs/TROUBLESHOOTING.md) - Common issues and solutions
+
+---
+
+## 🔗 Links
+
+- [GitHub Repository](https://github.com/hoainho/react-debugger-extension)
+- [Report Issues](https://github.com/hoainho/react-debugger-extension/issues)
+- [Changelog](https://github.com/hoainho/react-debugger-extension/releases)
+
+---
+
+## 📋 Requirements
+
+- Node.js >= 18.0.0
+- Chrome, Brave, Edge, or any Chromium-based browser
+- React 16+ application
 
-- [GitHub Repository](https://github.com/nhonh/react-debugger-extension)
-- [Report Issues](https://github.com/nhonh/react-debugger-extension/issues)
+---
 
-## License
+## 📄 License
 
 MIT © NhoNH

package/bin/cli.js

@@ -105,7 +105,7 @@ ${pc.yellow('Examples:')}
     console.error(pc.red('Error:'), err.message);
     console.error();
     console.error(pc.dim('If this persists, please report at:'));
-    console.error(pc.dim('https://github.com/nhonh/react-debugger-extension/issues'));
+    console.error(pc.dim('https://github.com/hoainho/react-debugger-extension/issues'));
     process.exit(1);
   }
 }

package/docs/GETTING-STARTED.md

@@ -0,0 +1,267 @@
+# Getting Started with React Debugger
+
+This guide walks you through installing and using the React Debugger extension for the first time.
+
+---
+
+## Table of Contents
+
+1. [Installation](#installation)
+2. [Loading the Extension](#loading-the-extension)
+3. [First Time Setup](#first-time-setup)
+4. [Understanding the Interface](#understanding-the-interface)
+5. [Your First Debug Session](#your-first-debug-session)
+
+---
+
+## Installation
+
+### Method 1: NPX (Recommended)
+
+The fastest way to get started:
+
+```bash
+npx @nhonh/react-debugger
+```
+
+You'll be prompted to choose an installation directory:
+
+```
+┌  React Debugger Extension Installer
+│
+◆  Where should we install the extension?
+│  ./react-debugger
+│
+◇  Downloading extension...
+│
+└  Success!
+```
+
+### Method 2: Direct Path
+
+Skip the prompt by specifying the path:
+
+```bash
+npx @nhonh/react-debugger ./my-react-debugger
+```
+
+### Method 3: Global Install
+
+Install globally to use anywhere:
+
+```bash
+npm install -g @nhonh/react-debugger
+react-debugger ./my-extension
+```
+
+---
+
+## Loading the Extension
+
+### Chrome / Brave / Edge
+
+1. **Open Extensions Page**
+   - Chrome: `chrome://extensions/`
+   - Brave: `brave://extensions/`
+   - Edge: `edge://extensions/`
+
+2. **Enable Developer Mode**
+   
+   Toggle the "Developer mode" switch in the top-right corner.
+
+   ![Developer Mode](https://raw.githubusercontent.com/hoainho/react-debugger-extension/main/docs/images/developer-mode.png)
+
+3. **Load the Extension**
+   
+   Click "Load unpacked" and select your installation folder.
+
+   ![Load Unpacked](https://raw.githubusercontent.com/hoainho/react-debugger-extension/main/docs/images/load-unpacked.png)
+
+4. **Verify Installation**
+   
+   You should see "React Debugger" in your extensions list.
+
+   ![Extension Loaded](https://raw.githubusercontent.com/hoainho/react-debugger-extension/main/docs/images/extension-loaded.png)
+
+---
+
+## First Time Setup
+
+### Opening the Debugger
+
+1. Navigate to any React website (e.g., [react.dev](https://react.dev))
+2. Open DevTools:
+   - **Mac**: `Cmd + Option + I`
+   - **Windows/Linux**: `F12` or `Ctrl + Shift + I`
+3. Find the **"React Debugger"** tab in DevTools
+
+![DevTools Tab](https://raw.githubusercontent.com/hoainho/react-debugger-extension/main/docs/images/devtools-location.png)
+
+### Initial State
+
+When you first open the debugger on a React page:
+
+- ✅ **"Recording"** badge appears - the debugger is active
+- ✅ **React version** is displayed in the header
+- ✅ **Timeline** starts collecting events
+
+If you see **"Waiting for React..."**, the page either:
+- Doesn't use React
+- Uses React < 16 (not supported)
+- Is still loading
+
+---
+
+## Understanding the Interface
+
+### Header Section
+
+```
+┌─────────────────────────────────────────────────────┐
+│ ⚛️ React Debugger  v1.0.0    [Recording] [Redux]   │
+│                                          [▶ Start] │
+└─────────────────────────────────────────────────────┘
+```
+
+| Element | Description |
+|---------|-------------|
+| Version | Extension version |
+| Recording | Green = active, Gray = paused |
+| Redux | Appears if Redux store detected |
+| Start/Stop | Toggle debugging on/off |
+
+### Tab Bar
+
+```
+┌──────────┬───────────┬─────────────┬────────┬─────────────┬─────┬───────┐
+│ Timeline │ UI & State│ Performance │ Memory │ Side Effects│ CLS │ Redux │
+└──────────┴───────────┴─────────────┴────────┴─────────────┴─────┴───────┘
+```
+
+Each tab shows a badge with issue count when problems are detected.
+
+### Status Indicators
+
+| Color | Meaning |
+|-------|---------|
+| 🟢 Green | Good / No issues |
+| 🟡 Yellow | Warning / Needs attention |
+| 🔴 Red | Error / Critical issue |
+| 🔵 Blue | Informational |
+
+---
+
+## Your First Debug Session
+
+Let's debug a simple React app to understand how the extension works.
+
+### Step 1: Open a React App
+
+For testing, use any of these:
+- Your local development server
+- [react.dev](https://react.dev)
+- [CodeSandbox React template](https://codesandbox.io/s/new)
+
+### Step 2: Check the Timeline
+
+1. Click the **Timeline** tab
+2. Interact with the page (click buttons, type in inputs)
+3. Watch events appear in real-time
+
+**What you'll see:**
+
+| Icon | Event Type | Example |
+|------|------------|---------|
+| 🔄 | Render | Component mounted or updated |
+| 📦 | State | useState or Redux state changed |
+| ⚡ | Effect | useEffect ran or cleaned up |
+| ❌ | Error | JavaScript error occurred |
+
+### Step 3: Find Issues
+
+1. Click the **UI & State** tab
+2. If issues exist, they appear as cards
+3. Click a card to expand details
+
+**Example issue:**
+
+```
+⚠️ INDEX_AS_KEY
+Component: TodoList
+Message: Using array index as key can cause issues with list reordering
+
+Suggestion: Use a unique identifier from your data as the key prop
+
+Code:
+  {items.map((item, index) => (
+    <li key={index}>{item}</li>  // ← Problem here
+  ))}
+```
+
+### Step 4: Check Performance
+
+1. Click the **Performance** tab
+2. Look at the statistics dashboard
+3. Check "Top Re-rendering Components"
+
+**What to look for:**
+
+| Metric | Good | Investigate |
+|--------|------|-------------|
+| Avg Render Time | < 16ms | > 16ms |
+| Renders per component | < 10 | > 20 |
+| Slow Renders | 0 | > 0 |
+
+### Step 5: Enable React Scan (Visual Mode)
+
+1. In **Performance** tab, find "React Scan"
+2. Toggle it ON
+3. Go back to your page - components flash colors on render
+
+**Color meanings:**
+
+| Color | Renders | Action |
+|-------|---------|--------|
+| 🟢 Green | 1 | Normal |
+| 🟡 Yellow | 2-3 | Monitor |
+| 🟠 Orange | 4-5 | Investigate |
+| 🔴 Red | 10+ | Optimize! |
+
+---
+
+## Next Steps
+
+Now that you understand the basics:
+
+1. **[Read the Tabs Guide](./TABS-GUIDE.md)** - Deep dive into each tab's features
+2. **[Check Troubleshooting](./TROUBLESHOOTING.md)** - If something isn't working
+3. **Experiment!** - The best way to learn is by debugging real issues
+
+---
+
+## Quick Reference
+
+### Keyboard Shortcuts
+
+| Action | Mac | Windows |
+|--------|-----|---------|
+| Open DevTools | `Cmd + Option + I` | `F12` |
+| Refresh page | `Cmd + R` | `Ctrl + R` |
+| Hard refresh | `Cmd + Shift + R` | `Ctrl + Shift + R` |
+
+### Useful Test Sites
+
+| Site | What to Test |
+|------|--------------|
+| [react.dev](https://react.dev) | General React detection |
+| [redux.js.org](https://redux.js.org) | Redux detection |
+| [Next.js docs](https://nextjs.org/docs) | SSR React app |
+| Your local app | Real issues! |
+
+---
+
+## Need Help?
+
+- 📖 [Full Documentation](https://github.com/hoainho/react-debugger-extension#readme)
+- 🐛 [Report a Bug](https://github.com/hoainho/react-debugger-extension/issues)
+- 💬 [Discussions](https://github.com/hoainho/react-debugger-extension/discussions)