@nhonh/react-debugger 1.0.0 → 1.0.1

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,416 @@
+# Troubleshooting Guide
+
+Solutions to common issues with React Debugger Extension.
+
+---
+
+## Table of Contents
+
+1. [Installation Issues](#installation-issues)
+2. [Extension Not Working](#extension-not-working)
+3. [React Not Detected](#react-not-detected)
+4. [Redux Not Detected](#redux-not-detected)
+5. [Performance Issues](#performance-issues)
+6. [Data Not Showing](#data-not-showing)
+7. [Error Messages](#error-messages)
+
+---
+
+## Installation Issues
+
+### NPX command fails
+
+**Error:**
+```
+npm ERR! code ENOENT
+npm ERR! syscall spawn
+```
+
+**Solution:**
+1. Update Node.js to version 18+
+2. Clear npm cache: `npm cache clean --force`
+3. Try again: `npx @nhonh/react-debugger`
+
+---
+
+### "Permission denied" error
+
+**Error:**
+```
+EACCES: permission denied
+```
+
+**Solution:**
+```bash
+# Use a different directory
+npx @nhonh/react-debugger ~/Desktop/react-debugger
+
+# Or fix permissions
+sudo chown -R $USER ~/.npm
+```
+
+---
+
+### Extension won't load in Chrome
+
+**Symptoms:**
+- "Load unpacked" button doesn't work
+- Error: "Manifest file is missing or unreadable"
+
+**Solutions:**
+
+1. **Check you selected the correct folder**
+   - Should contain `manifest.json`
+   - Not the parent folder
+
+2. **Re-download**
+   ```bash
+   rm -rf ./react-debugger
+   npx @nhonh/react-debugger ./react-debugger
+   ```
+
+3. **Check Chrome version**
+   - Requires Chrome 88+
+   - Update if needed
+
+---
+
+## Extension Not Working
+
+### Tab doesn't appear in DevTools
+
+**Solutions:**
+
+1. **Refresh the page** after loading extension
+
+2. **Close and reopen DevTools** completely
+
+3. **Check extension is enabled**
+   - Go to `chrome://extensions/`
+   - Ensure toggle is ON
+
+4. **Check for conflicts**
+   - Disable other React extensions temporarily
+   - Especially "React Developer Tools"
+
+---
+
+### "Extension context invalidated" error
+
+**Cause:** Extension was updated/reloaded while DevTools was open.
+
+**Solution:**
+1. Close DevTools
+2. Close the tab
+3. Reopen the page and DevTools
+
+---
+
+### Recording badge shows "Paused"
+
+**Solution:**
+1. Click the Start/Stop button to enable recording
+2. Refresh the page
+3. Check if the page has React
+
+---
+
+## React Not Detected
+
+### "Waiting for React..." message
+
+**Possible causes:**
+
+1. **Page doesn't use React**
+   - Check with: Open console, type `window.React`
+   - If undefined, page isn't using React
+
+2. **React version too old**
+   - Requires React 16+ (Fiber architecture)
+   - React 15 and below not supported
+
+3. **React loaded after page**
+   - Wait for full page load
+   - Try refreshing
+
+4. **Production build without DevTools**
+   - Some builds strip React globals
+   - Check `__REACT_DEVTOOLS_GLOBAL_HOOK__`
+
+**Debug steps:**
+```javascript
+// In browser console:
+console.log('React:', typeof React);
+console.log('DevTools Hook:', !!window.__REACT_DEVTOOLS_GLOBAL_HOOK__);
+
+// Find React root
+const root = document.getElementById('root');
+const keys = Object.keys(root);
+console.log('Fiber keys:', keys.filter(k => k.includes('react')));
+```
+
+---
+
+### Works on some sites but not others
+
+**Possible reasons:**
+
+1. **Shadow DOM** - React inside Shadow DOM is harder to detect
+
+2. **Iframes** - React in iframes has separate context
+
+3. **Server Components** - RSC in Next.js 13+ may not show client components
+
+4. **Micro-frontends** - Multiple React instances
+
+---
+
+## Redux Not Detected
+
+### Redux tab shows "Redux not detected"
+
+**Check these in order:**
+
+1. **Is Redux actually used?**
+   ```javascript
+   // In console:
+   console.log(window.__REDUX_DEVTOOLS_EXTENSION__);
+   console.log(window.store);
+   ```
+
+2. **Expose store for debugging**
+   ```jsx
+   // In your app's store setup
+   const store = configureStore({ reducer: rootReducer });
+   
+   if (process.env.NODE_ENV === 'development') {
+     window.store = store;
+   }
+   ```
+
+3. **Install Redux DevTools Extension**
+   - [Chrome Web Store](https://chrome.google.com/webstore/detail/redux-devtools)
+   - Our extension can use its connection
+
+4. **Use DevTools enhancer**
+   ```jsx
+   import { configureStore } from '@reduxjs/toolkit';
+   
+   // RTK automatically connects to DevTools
+   const store = configureStore({
+     reducer: rootReducer,
+     devTools: process.env.NODE_ENV !== 'production',
+   });
+   ```
+
+---
+
+### Redux detected but state is empty
+
+**Cause:** Store might be created but not yet populated.
+
+**Solutions:**
+1. Wait for app to initialize
+2. Dispatch an action to trigger update
+3. Check if store is the correct instance
+
+---
+
+## Performance Issues
+
+### Extension makes page slow
+
+**Solutions:**
+
+1. **Pause recording** when not debugging
+   - Click the Stop button
+
+2. **Disable React Scan** when not needed
+   - Visual overlay has overhead
+
+3. **Clear old data**
+   - Click "Clear" in Timeline
+   - Reduces memory usage
+
+4. **Limit history**
+   - Extension keeps last 2000 events
+   - Old events auto-purge
+
+---
+
+### DevTools panel is slow/laggy
+
+**Solutions:**
+
+1. **Filter events** - Show only what you need
+
+2. **Collapse sections** - In Redux state tree
+
+3. **Reduce timeline scope** - Clear frequently
+
+4. **Close other DevTools tabs** - Elements, Network, etc.
+
+---
+
+## Data Not Showing
+
+### Timeline is empty
+
+**Checklist:**
+- [ ] Recording is enabled (green badge)
+- [ ] React is detected
+- [ ] You interacted with the page
+- [ ] Correct tab is selected (check tabId)
+
+**Try:**
+1. Click in the page to trigger events
+2. Change state in your app
+3. Check filter buttons aren't hiding events
+
+---
+
+### Performance metrics show N/A
+
+**Cause:** Metrics require Navigation Timing API.
+
+**This happens when:**
+- Page is in an iframe
+- Page was restored from cache
+- DevTools opened after load
+
+**Solution:** Hard refresh: `Cmd+Shift+R` / `Ctrl+Shift+R`
+
+---
+
+### Memory tab shows no data
+
+**Requirements:**
+- `performance.memory` API (Chrome only)
+- Not available in Firefox/Safari
+
+**Check:**
+```javascript
+console.log(performance.memory); // Should show object
+```
+
+---
+
+## Error Messages
+
+### "Cannot read property 'X' of undefined"
+
+**Where it occurs:** Usually in Panel when data is malformed.
+
+**Solutions:**
+1. Refresh the page
+2. Reload the extension
+3. Report bug if persistent
+
+---
+
+### "Extension context invalidated"
+
+**Cause:** Extension reloaded while DevTools open.
+
+**Solution:**
+1. Close DevTools completely
+2. Refresh the page
+3. Reopen DevTools
+
+---
+
+### "Manifest version 2 is deprecated"
+
+**Note:** This is a warning, not an error. Extension still works.
+
+Future versions will migrate to Manifest V3.
+
+---
+
+### Console errors from extension
+
+**Safe to ignore:**
+- `DevTools failed to load SourceMap`
+- `Could not establish connection`
+
+**Report if you see:**
+- `Uncaught TypeError` from panel.js
+- `Uncaught ReferenceError` from inject.js
+
+---
+
+## Still Having Issues?
+
+### Debug Mode
+
+Enable verbose logging:
+```javascript
+// In browser console
+localStorage.setItem('REACT_DEBUGGER_DEBUG', 'true');
+// Then refresh
+```
+
+### Collect Debug Info
+
+When reporting a bug, include:
+
+1. **Browser & version**
+   ```
+   chrome://version/
+   ```
+
+2. **Extension version**
+   - Shown in header: "v1.0.0"
+
+3. **React version**
+   - Shown when detected
+
+4. **Console errors**
+   - Right-click panel → Inspect
+   - Copy errors from Console
+
+5. **Steps to reproduce**
+   - What you did
+   - What you expected
+   - What happened
+
+### Report a Bug
+
+[Open an issue on GitHub](https://github.com/hoainho/react-debugger-extension/issues/new)
+
+Include:
+- Debug info above
+- Screenshots if helpful
+- Minimal reproduction if possible
+
+---
+
+## FAQ
+
+### Q: Does this work with Next.js?
+
+**A:** Yes! Works with any React framework:
+- Next.js
+- Remix
+- Gatsby
+- Create React App
+- Vite
+
+### Q: Does this work in Firefox?
+
+**A:** Currently Chrome/Chromium only. Firefox support planned.
+
+### Q: Is my data sent anywhere?
+
+**A:** No. All data stays in your browser. The extension:
+- Has no analytics
+- Makes no network requests (except download)
+- Stores nothing persistently
+
+### Q: Will this slow down production?
+
+**A:** The extension only activates in DevTools. It doesn't affect production users who don't have it installed.
+
+### Q: Can I use this with React Native?
+
+**A:** No. This is for React DOM (web) only.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nhonh/react-debugger",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Advanced debugging & performance optimization tool for ReactJS applications - Chrome Extension",
   "author": "NhoNH",
   "license": "MIT",
@@ -10,7 +10,9 @@
   },
   "files": [
     "bin/",
-    "src/"
+    "src/",
+    "docs/",
+    "README.md"
   ],
   "keywords": [
     "react",
@@ -24,11 +26,11 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/nhonh/react-debugger-extension.git"
+    "url": "git+https://github.com/hoainho/react-debugger-extension.git"
   },
-  "homepage": "https://github.com/nhonh/react-debugger-extension#readme",
+  "homepage": "https://github.com/hoainho/react-debugger-extension#readme",
   "bugs": {
-    "url": "https://github.com/nhonh/react-debugger-extension/issues"
+    "url": "https://github.com/hoainho/react-debugger-extension/issues"
   },
   "engines": {
     "node": ">=18.0.0"

package/src/install.js

@@ -3,7 +3,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import decompress from 'decompress';
 
-const GITHUB_REPO = 'nhonh/react-debugger-extension';
+const GITHUB_REPO = 'hoainho/react-debugger-extension';
 const RELEASE_TAG = 'latest';
 
 async function getLatestReleaseUrl() {