React Native Debug Toolkit

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

Installation

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:

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

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

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

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

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

Run pod install in your iOS directory:

cd ios && pod install

Android Additional Setup

Add the following to your android/settings.gradle:

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

Add these dependencies to your android/app/build.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')
}

Initialize DoKit in your MainApplication.kt:

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:

// 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:

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:

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:

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:

// 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:

// 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