react-native-debug-toolkit 0.6.4 → 2.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 zcj
+
+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.

package/README.md

@@ -1,271 +1,209 @@
 # React Native Debug Toolkit
 
-A simple yet powerful debugging toolkit for React Native with a convenient floating UI for development.
+[中文文档](README.zh-CN.md)
 
-## Installation
-
-```bash
-npm install react-native-debug-toolkit
-# or
-yarn add react-native-debug-toolkit
-```
+A dev-only floating debug panel for React Native — inspect network, console, state, navigation and more, right on your device.
 
-### iOS Additional Setup
+> Zero impact on production builds (`__DEV__` only).
 
-This toolkit uses FLEX and DoraemonKit for iOS debugging features. To properly integrate:
+## Features
 
-1. Make sure CocoaPods is installed in your project
-2. Add these dependencies to your Podfile:
+- **Network** — Auto-intercepts fetch / XMLHttpRequest, inspect requests & responses, copy as cURL
+- **Console** — Capture `console.log / info / warn / error`
+- **Zustand** — Log state transitions via middleware
+- **Navigation** — Track route changes
+- **Track** — Record custom analytics events
+- **Environment** — Switch API hosts on the fly
+- **Clipboard** — Paste text and copy to computer
 
-```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
+## Installation
 
-  #ifdef DEBUG
-  DoraemonManager *doKit = [DoraemonManager shareInstance];
-  doKit.autoDock = false;
-  [doKit install];
-  [doKit hiddenDoraemon];
-  #endif
+```bash
+npm install react-native-debug-toolkit
 ```
 
-4. Run pod install in your iOS directory:
+Optional — clipboard copy support:
 
 ```bash
-cd ios && pod install
+npm install @react-native-clipboard/clipboard
 ```
 
-### Android Additional Setup
-
-1. Add the following to your `android/settings.gradle`:
+## Quick Start
 
-```gradle
-include ':react-native-debug-toolkit'
-project(':react-native-debug-toolkit').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-debug-toolkit/android')
-```
+```tsx
+import { DebugView } from 'react-native-debug-toolkit';
 
-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')
+function App() {
+  return (
+    <DebugView>
+      <AppContent />
+    </DebugView>
+  );
 }
 ```
 
-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()
-}
-```
+That's it. A floating debug button appears in dev mode. Tap to open the panel.
 
-## Basic Usage
+Network (fetch and XMLHttpRequest), console, navigation, track, and clipboard features are enabled by default. In React Native and Expo, Axios is covered through the XMLHttpRequest layer, so no Axios setup is required.
 
-The easiest way to add the debug toolkit to your app is using the `initializeDebugToolkit` function with default features:
+### With Navigation Tracking
 
-```javascript
-// In your App.js or other initialization file
-import React, { useEffect } from 'react';
-import { initializeDebugToolkit, isDebugMode } from 'react-native-debug-toolkit';
+```tsx
+import { useRef } from 'react';
+import { DebugView } from 'react-native-debug-toolkit';
+import { NavigationContainer } from '@react-navigation/native';
 
 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 />;
+  const navRef = useRef(null);
+  return (
+    <DebugView navigationRef={navRef}>
+      <NavigationContainer ref={navRef}>
+        <AppContent />
+      </NavigationContainer>
+    </DebugView>
+  );
 }
 ```
 
-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
+### With Environment Switching
+
+```tsx
+<DebugView
+  environments={[
+    { id: 'dev',  label: 'Dev',  host: 'dev-api.example.com', color: '#34C759' },
+    { id: 'prod', label: 'Prod', host: 'api.example.com',     color: '#FF3B30' },
+  ]}
+>
+  <AppContent />
+</DebugView>
+```
 
-By initializing with the single line of code above, you'll automatically get access to all these debugging features:
+### Disable Specific 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)
+```tsx
+<DebugView features={{ clipboard: false, zustand: false }}>
+  <AppContent />
+</DebugView>
+```
 
-## Integration
+## `<DebugView>` Props
 
-### Advanced Axios Network Tracking
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | — | App content |
+| `features` | `Partial<FeatureConfigs>` | all enabled | Enable/disable features |
+| `navigationRef` | `RefObject` | — | Navigation container ref |
+| `environments` | `EnvironmentConfig[]` | — | Environment configs |
+| `enabled` | `boolean` | `__DEV__` | Force enable/disable |
 
-For projects using Axios, you can enable more detailed network request tracking:
+### Per-feature options
 
-```javascript
-import axios from 'axios';
-import { createNetworkFeature, isDebugMode } from 'react-native-debug-toolkit';
+| Feature | Options |
+|---------|---------|
+| `network` | `maxLogs`, `blacklist` |
+| `console` | `maxLogs` |
+| `zustand` | `maxLogs` |
+| `navigation` | `maxLogs` |
+| `track` | `maxLogs` |
+| `environment` | `EnvironmentConfig[]` |
+| `clipboard` | — |
 
-// 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
-}
-```
+All `maxLogs` default to **200**.
 
-### Monitoring Zustand Stores (If You Use Zustand)
+## Usage Examples
 
-If your app uses Zustand for state management, just add the middleware to track all state changes:
+### Zustand middleware
 
-```javascript
-import { create } from 'zustand';
+```tsx
 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 })),
-    })
-  )
+  zustandLogMiddleware((set) => ({
+    count: 0,
+    increment: () => set((s) => ({ count: s.count + 1 }), false, 'increment'),
+  }))
 );
 ```
 
-### Navigation Tracking (React Navigation)
+### Custom events
 
-If you're using React Navigation, adding navigation tracking is just one step:
+```tsx
+import { addTrackLog } from 'react-native-debug-toolkit';
 
-```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>
-  );
-}
+addTrackLog({ eventName: 'button_click', buttonId: 'submit' });
 ```
 
-## Custom Configuration
+### Copy to computer
 
-If you don't need all features, you can selectively enable specific ones:
+```tsx
+import { copyToComputer } from 'react-native-debug-toolkit';
+
+await copyToComputer(jsonString);
+```
 
-```javascript
-// Only enable network and console logging features
-initializeDebugToolkit(['network', 'console']);
+## Advanced: Imperative API
 
-// Or specify a custom set of features
-initializeDebugToolkit([
-  'network',
-  'console', 
-  'zustand', 
-  'navigation',
-  'thirdPartyLibs'
-]);
+For programmatic control outside React components:
+
+```tsx
+import { initializeDebugToolkit } from 'react-native-debug-toolkit';
+
+const toolkit = initializeDebugToolkit({
+  features: { network: { maxLogs: 100 }, console: true },
+  enabled: true,
+});
+
+toolkit?.showPanel();
+toolkit?.clearAll();
+toolkit?.destroy();
 ```
 
-## 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 = [];
-    }
-  };
+### `DebugToolkit` methods
+
+| Method | Description |
+|--------|-------------|
+| `showPanel()` / `hidePanel()` | Toggle visibility |
+| `clearAll()` | Clear all data |
+| `addFeature(f)` / `removeFeature(name)` | Manage features at runtime |
+| `destroy()` | Full teardown |
+| `features` | Active features (read-only) |
+
+### Custom feature
+
+```tsx
+import type { DebugFeature } from 'react-native-debug-toolkit';
+
+const myFeature: DebugFeature<MyData> = {
+  name: 'myFeature',
+  label: 'My Feature',
+  setup:     () => { /* start capturing */ },
+  getData:   () => myDataArray,
+  cleanup:   () => { /* stop capturing */ },
+  clear:     () => { /* reset data */ },
+  subscribe: (cb) => { emitter.on('change', cb); return () => emitter.off('change', cb); },
+  renderContent: MyFeatureTab,
 };
 
-// Usage with initializeDebugToolkit
-initializeDebugToolkit(['network', 'console', createMyCustomFeature]);
+const toolkit = initializeDebugToolkit();
+toolkit?.addFeature(myFeature);
 ```
 
-## Troubleshooting
+### Utilities
+
+| Export | Description |
+|--------|-------------|
+| `safeStringify(value, space?)` | JSON stringify with circular-ref protection |
+| `copyToComputer(content, options?)` | Copy content to computer |
+| `logToComputer(...args)` | Log to computer console |
 
-### Debug panel not showing
-- Make sure you're in development mode (`isDebugMode` is true)
-- Check that you've correctly called `initializeDebugToolkit()`
+## Peer Dependencies
 
-### 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
+| Package | Version | Required |
+|---------|---------|----------|
+| react | >= 18.0.0 | Yes |
+| react-native | >= 0.72.0 | Yes |
+| @react-native-clipboard/clipboard | >= 1.0.0 | No |
 
-### Network requests not captured
-- For Axios, ensure you've called `setupAxiosInterceptors(axios)`
-- For fetch requests, the toolkit should automatically intercept them without additional configuration
+## License
 
-### 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
+MIT