React Debugger

A lightweight SDK that connects your React or React Native app to the React Debugger VS Code extension — giving you real-time network inspection, console logs, state management debugging, performance monitoring, UI inspection, and more.

✨ Features

• 🌐 Network Interceptor: Automatically captures all fetch, XMLHttpRequest, and WebSocket traffic
• 📝 Console Interceptor: Captures console.log, warn, error, debug with full stack traces
• 🗃️ State Management: Redux middleware + Zustand support with time-travel state diffs
• ⚡ Performance Monitor: Real-time FPS, memory, and CPU metrics
• 🔍 UI Inspector: Captures your React component tree via the fiber tree
• 💾 Storage Inspector: Reads and manages AsyncStorage / localStorage entries
• 🧭 Navigation Tracker: Reports route changes and params from React Navigation or custom routers
• 🛡️ Dev-Only: Only activates when __DEV__ === true — zero impact in production builds
• 📝 TypeScript: Full TypeScript support
• 📱 Cross-Platform: Works with React (web), React Native (iOS & Android), and Expo

📦 Installation

npm install @amrshbib/react-debugger
# or
yarn add @amrshbib/react-debugger

Note: This package is designed to work alongside the React Debugger VS Code extension, which provides the real-time UI for inspecting your app. Install the extension from the VS Code Marketplace.

Peer Dependencies

• react (required)
• react-native (optional — only needed for React Native apps)
• @react-native-async-storage/async-storage (optional — only needed for Storage Inspector on React Native)

🚀 Quick Start

Step 1: Install the Package

npm install @amrshbib/react-debugger
# or
yarn add @amrshbib/react-debugger

Step 2: Initialize the Debugger

Add initDebugger() at the very top of your app entry point (e.g. index.js, App.tsx). This must be called before any console.log, fetch, or state changes so the SDK can intercept them.

// index.js or App.tsx
import { initDebugger } from "@amrshbib/react-debugger";

initDebugger();

That's it. Once called, the SDK automatically:

• Connects to the debugger server via WebSocket (localhost:8347)
• Intercepts fetch, XMLHttpRequest, console.*, and performance metrics
• Sends all data to the VS Code extension in real time
• Only runs in __DEV__ mode — zero impact in production

Step 3: Set Up Redux Middleware (Optional)

If your app uses Redux, add debuggerMiddleware to your store to enable state debugging with action tracking, state snapshots, and diffs.

import { configureStore } from "@reduxjs/toolkit";
import { debuggerMiddleware } from "@amrshbib/react-debugger";
import rootReducer from "./reducers";

const store = configureStore({
  reducer: rootReducer,
  middleware: (getDefaultMiddleware) =>
    getDefaultMiddleware().concat(debuggerMiddleware),
});

export default store;

What this gives you in the debugger:

• Every dispatched action (type + payload)
• State snapshot before and after each action
• Computed diffs between states
• Time-travel through action history

The middleware is a no-op in production (__DEV__ === false), so it's safe to leave in your code.

Legacy Redux (createStore):

import { createStore, applyMiddleware } from "redux";
import { debuggerMiddleware } from "@amrshbib/react-debugger";
import rootReducer from "./reducers";

const store = createStore(rootReducer, applyMiddleware(debuggerMiddleware));

Step 4: Set Up Navigation Tracking (Optional)

Track route changes in the debugger to see navigation history, route names, and params in real time.

React Navigation (recommended):

Use onStateChange on NavigationContainer combined with a ref to get the current route name and params:

import { useRef } from "react";
import { NavigationContainer } from "@react-navigation/native";
import {
  reportNavigation,
  reportNavigationEvent,
} from "@amrshbib/react-debugger";

const App = () => {
  const navigationRef = useRef(null);

  const onStateChange = (state) => {
    // Report full navigation state tree (for deep state inspection)
    reportNavigation(state);

    // Report the current route name + params (for navigation logs)
    const currentRoute = navigationRef.current?.getCurrentRoute();
    if (currentRoute) {
      reportNavigationEvent(currentRoute.name, currentRoute.params);
    }
  };

  return (
    <NavigationContainer ref={navigationRef} onStateChange={onStateChange}>
      {/* Your screens */}
    </NavigationContainer>
  );
};

React Router (web):

import { useLocation } from "react-router-dom";
import { useEffect } from "react";
import { reportNavigationEvent } from "@amrshbib/react-debugger";

function NavigationTracker() {
  const location = useLocation();

  useEffect(() => {
    reportNavigationEvent(location.pathname, {
      search: location.search,
      hash: location.hash,
      state: location.state,
    });
  }, [location]);

  return null;
}

// Add <NavigationTracker /> inside your <BrowserRouter>

Custom router / manual reporting:

import { reportNavigationEvent } from "@amrshbib/react-debugger";

// Call this wherever your app navigates
reportNavigationEvent("ProfileScreen", { userId: 123 });

Step 5: Open the VS Code Extension

1. Open VS Code in your project
2. Click the React Debugger icon in the Activity Bar (sidebar)
3. Or press Ctrl+Shift+P / Cmd+Shift+P → React Debugger: Open Debugger
4. Start your app — it will auto-connect and data will appear in real time

📖 API Reference

initDebugger()

Initializes the debugger SDK and connects to the debug server. Only runs in development mode.

Example:

import { initDebugger } from "@amrshbib/react-debugger";

initDebugger();

debuggerMiddleware

Redux middleware that captures dispatched actions, state snapshots, and state diffs.

Example:

import { configureStore } from "@reduxjs/toolkit";
import { debuggerMiddleware } from "@amrshbib/react-debugger";

const store = configureStore({
  reducer: rootReducer,
  middleware: (getDefaultMiddleware) =>
    getDefaultMiddleware().concat(debuggerMiddleware),
});

reportNavigation(state)

Reports the current navigation state to the debugger. Use with React Navigation's onStateChange.

Parameters:

• state (Object): The navigation state object from React Navigation

Example:

import { reportNavigation } from "@amrshbib/react-debugger";

<NavigationContainer onStateChange={(state) => reportNavigation(state)}>
  {/* ... */}
</NavigationContainer>

reportNavigationEvent(routeName, params)

Manually reports a navigation event for custom routers.

Parameters:

• routeName (string): The name of the route
• params (Object, optional): Route parameters

Example:

import { reportNavigationEvent } from "@amrshbib/react-debugger";

reportNavigationEvent("HomeScreen", { userId: 123 });

reportComponentTree(tree)

Manually reports a component tree snapshot to the UI Inspector.

Parameters:

• tree (Object): The component tree structure

disconnectDebugger()

Cleanly disconnects from the debug server and restores all intercepted globals (fetch, console, XMLHttpRequest).

Example:

import { disconnectDebugger } from "@amrshbib/react-debugger";

// Call when you want to stop debugging
disconnectDebugger();

🏗️ What Gets Captured Automatically

Once initDebugger() is called, the SDK automatically intercepts:

| Domain | What's Captured | How | |--------|----------------|-----| | Network | All fetch and XMLHttpRequest calls | Global monkey-patching | | Console | console.log, warn, error, debug | Console interception | | Performance | FPS, memory (JS heap), CPU | requestAnimationFrame + performance.memory | | UI Inspector | React component tree | React DevTools fiber hook | | Storage | AsyncStorage / localStorage entries | On-demand capture via commands |

No additional code is needed beyond initDebugger() for these features.

⚠️ Important Notes

Development Only

The SDK checks for __DEV__ and does nothing in production builds. You can safely leave the initDebugger() call in your code — it will be a no-op in release mode.

Server Connection

• Default server: localhost:8347 (the VS Code extension's embedded server)
• The SDK auto-reconnects if the connection drops
• Heartbeat pings keep the connection alive

Multiple Devices

Multiple apps/devices can connect to the same VS Code debugger server simultaneously — each appears as a separate session in the extension.

🔧 Troubleshooting

SDK Not Connecting

1. Make sure the React Debugger VS Code extension is installed and active
2. Check that port 8347 is accessible (not blocked by firewall)
3. For physical devices, use your machine's local IP instead of localhost
4. Verify __DEV__ is true in your build

Console Logs Not Appearing

1. Ensure initDebugger() is called before any console.log calls
2. Place the init call at the very top of your app entry point

State Changes Not Tracked

1. Verify debuggerMiddleware is added to your Redux store
2. For Zustand, use the SDK's store subscription helpers

Performance Impact

The SDK is designed to have minimal overhead, but for very high-frequency operations:

1. Network interception adds a small wrapper around fetch / XHR
2. Console interception adds a forwarding layer
3. Performance monitor uses requestAnimationFrame for FPS tracking

📋 Requirements

• React 18+
• React Native 0.70+ (for React Native apps)
• Node.js 18+
• VS Code with the React Debugger extension installed

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

The MIT License

Copyright (c) 2026 Amr Shbib

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.

🔗 Links

• npm Package
• VS Code Extension

Made with ❤️ for the React and React Native community