react-native-debug-toolkit/README.md

A simple yet powerful debugging toolkit for React Native with a convenient floating UI for development

# React Native Debug Toolkit

A simple yet powerful debugging toolkit for React Native with a convenient floating UI for development.

## Installation

```bash
npm install react-native-debug-toolkit
# or
yarn add react-native-debug-toolkit
```

### iOS Additional Setup

This toolkit uses FLEX and DoraemonKit for iOS debugging features. To properly integrate:

1. Make sure CocoaPods is installed in your project
2. Add these dependencies to your Podfile:

```ruby
pod 'FLEX', :configurations => ['Debug']
pod 'DoraemonKit/Core', :configurations => ['Debug']
```

3. Add the following code to your AppDelegate.m in the `didFinishLaunchingWithOptions` method:

```objc
#ifdef DEBUG
#import <DoraemonKit/DoraemonManager.h>
#endif

  #ifdef DEBUG
  DoraemonManager *doKit = [DoraemonManager shareInstance];
  doKit.autoDock = false;
  [doKit install];
  [doKit hiddenDoraemon];
  #endif
```

4. Run pod install in your iOS directory:

```bash
cd ios && pod install
```

### Android Additional Setup

1. Add the following to your `android/settings.gradle`:

```gradle
include ':react-native-debug-toolkit'
project(':react-native-debug-toolkit').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-debug-toolkit/android')
```

2. Add these dependencies to your `android/app/build.gradle`:

```gradle
dependencies {
    // Other dependencies...
    
    debugImplementation 'io.github.didi.dokit:dokitx:3.7.1'
    releaseImplementation 'io.github.didi.dokit:dokitx-no-op:3.7.1'
    debugImplementation 'com.android.volley:volley:1.2.0'
    
    implementation project(':react-native-debug-toolkit')
}
```

3. Initialize DoKit in your `MainApplication.kt`:

```kotlin
import com.didichuxing.doraemonkit.DoKit

// Inside onCreate method
if (BuildConfig.DEBUG) {
    DoKit.Builder(this)
        .build()
    DoKit.hide()
}
```

## Basic Usage

The easiest way to add the debug toolkit to your app is using the `initializeDebugToolkit` function with default features:

```javascript
// In your App.js or other initialization file
import React, { useEffect } from 'react';
import { initializeDebugToolkit, isDebugMode } from 'react-native-debug-toolkit';

function App() {
  useEffect(() => {
    if (isDebugMode) {
      // Initialize with all default features
      initializeDebugToolkit();
      
      // Or select specific built-in features
      // initializeDebugToolkit(['network', 'console', 'zustand', 'navigation', 'thirdPartyLibs']);
    }
    
    return () => {
      // Cleanup happens automatically
    };
  }, []);
  
  return <YourApp />;
}
```

That's it! Your app will now display a floating debug panel in development mode, giving you access to all debugging features.

## Built-in Features

By initializing with the single line of code above, you'll automatically get access to all these debugging features:

- **Network**: Track and inspect all network requests and responses
- **Console**: View all console logs within the app
- **Zustand**: Monitor Zustand state management (if your app uses Zustand)
- **Navigation**: Automatically track navigation events in your app
- **ThirdPartyLibs**: Quick access to native debugging tools (FLEX for iOS, DoraemonKit)

## Integration

### Advanced Axios Network Tracking

For projects using Axios, you can enable more detailed network request tracking:

```javascript
import axios from 'axios';
import { createNetworkFeature, isDebugMode } from 'react-native-debug-toolkit';

// Get network feature instance and set up Axios interceptors
if (isDebugMode) {
  const networkFeature = createNetworkFeature();
  networkFeature.setupAxiosInterceptors(axios);
  
  // Optional: exclude sensitive URLs (like authentication endpoints)
  networkFeature.addUrlToBlacklist('api.example.com/auth');
  networkFeature.addUrlToBlacklist(/password/i); // Regex patterns supported
}
```

### Monitoring Zustand Stores (If You Use Zustand)

If your app uses Zustand for state management, just add the middleware to track all state changes:

```javascript
import { create } from 'zustand';
import { zustandLogMiddleware } from 'react-native-debug-toolkit';

// Simply add zustandLogMiddleware to wrap your store
const useStore = create(
  zustandLogMiddleware(
    (set) => ({
      count: 0,
      increment: () => set((state) => ({ count: state.count + 1 })),
      decrement: () => set((state) => ({ count: state.count - 1 })),
    })
  )
);
```

### Navigation Tracking (React Navigation)

If you're using React Navigation, adding navigation tracking is just one step:

```javascript
import React, { useRef } from 'react';
import { NavigationContainer } from '@react-navigation/native';
import { useNavigationLogger } from 'react-native-debug-toolkit';

function AppNavigator() {
  const navigationRef = useRef(null);
  
  // Add this line to enable navigation logging
  useNavigationLogger(navigationRef);
  
  return (
    <NavigationContainer ref={navigationRef}>
      {/* Your navigation configuration */}
    </NavigationContainer>
  );
}
```

## Custom Configuration

If you don't need all features, you can selectively enable specific ones:

```javascript
// Only enable network and console logging features
initializeDebugToolkit(['network', 'console']);

// Or specify a custom set of features
initializeDebugToolkit([
  'network',
  'console', 
  'zustand', 
  'navigation',
  'thirdPartyLibs'
]);
```

## Creating Custom Debug Features

You can create your own custom debugging features:

```javascript
// In myCustomFeature.js
export const createMyCustomFeature = () => {
  let customData = [];
  
  return {
    name: 'custom',         // Unique identifier
    label: 'My Custom Feature', // Display name in UI
    
    setup: () => {
      // Initialize your feature
      console.log('My custom feature initialized');
      
      // Start capturing data, set up listeners, etc.
      const interval = setInterval(() => {
        customData.push({
          timestamp: new Date(),
          value: Math.random() * 100
        });
        
        // Limit the amount of data stored
        if (customData.length > 100) {
          customData.shift();
        }
      }, 1000);
      
      // Return cleanup function if needed
      return () => clearInterval(interval);
    },
    
    getData: () => {
      // Return data to display in the panel
      return customData;
    },
    
    cleanup: () => {
      // Clean up any listeners or resources
      customData = [];
    }
  };
};

// Usage with initializeDebugToolkit
initializeDebugToolkit(['network', 'console', createMyCustomFeature]);
```

## Troubleshooting

### Debug panel not showing
- Make sure you're in development mode (`isDebugMode` is true)
- Check that you've correctly called `initializeDebugToolkit()`

### iOS features not working
- Verify that you've added FLEX and DoraemonKit to your Podfile
- Run `pod install` again after making changes
- Make sure you're running a Debug build

### Network requests not captured
- For Axios, ensure you've called `setupAxiosInterceptors(axios)`
- For fetch requests, the toolkit should automatically intercept them without additional configuration

### App performance issues
- This debug toolkit is meant for development only, ensure it's not included in production builds
- If performance is affected in development mode, try enabling only specific features