React Native API Debugger

A comprehensive network request debugging tool for React Native applications. Monitor, inspect, and debug all your app's network requests with an intuitive draggable overlay interface.

✨ Features

• 🔍 Real-time Network Monitoring - Automatically intercepts all fetch() and XMLHttpRequest calls
• 🎯 Draggable Overlay Interface - Non-intrusive floating button that can be moved anywhere on screen
• 📊 Comprehensive Request Details - View headers, body, response, timing, and status codes
• 📋 cURL Generation - Copy requests as cURL commands for easy debugging
• 🔎 Advanced Filtering - Search and filter by URL, method, status, or API endpoints
• ❌ Error Tracking - Easily identify failed requests and network errors
• 📱 Device Shake Support - Optional shake-to-show/hide functionality
• 📋 Copy to Clipboard - Optionally copy request/response/cURL details
• 🎨 Customizable UI - Configure header visibility and other display options
• 🚀 TypeScript Support - Full TypeScript definitions included
• 💾 Memory Efficient - Automatic cleanup with configurable request limits

📦 Installation

npm install react-native-api-debugger

Note: Features like draggable overlay, device shake, and clipboard copy require additional peer dependencies.
The debugger will throw a clear error if you enable a feature and the relevant library is not installed.

Optional Peer Dependencies

Install these only if you need advanced features:

npm install @react-native-clipboard/clipboard     # For copy to clipboard
npm install react-native-shake                   # For device shake to show/hide
npm install react-native-gesture-handler         # For draggable floating button
npm install react-native-reanimated              # (Required for gesture handler)

Note: For Expo SDK ≤ 53, use react-native-reanimated version 3.x.x

Platform Setup

If you use draggable overlay or device shake, also follow their respective setup guides:

• react-native-gesture-handler: Installation Guide
• react-native-reanimated: Installation Guide

🚀 Quick Start

Minimal Example

import React, { useEffect } from 'react';
import { View } from 'react-native';
import { networkLogger, NetworkLoggerOverlay } from 'react-native-api-debugger';

export default function App() {
  useEffect(() => {
    networkLogger.setupInterceptor();
  }, []);

  return (
    <View style={{ flex: 1 }}>
      {/* Your app content */}

      {/* Minimal usage: All advanced features turned off */}
      <NetworkLoggerOverlay
        draggable={false}
        enableDeviceShake={false}
        useCopyToClipboard={false}
        showRequestHeader={false}
        showResponseHeader={false}
        networkLogger={networkLogger}
      />
    </View>
  );
}

Full Features Example

<NetworkLoggerOverlay
  networkLogger={networkLogger}
  draggable={true}                // Requires react-native-gesture-handler & react-native-reanimated
  enableDeviceShake={true}        // Requires react-native-shake
  useCopyToClipboard={true}       // Requires @react-native-clipboard/clipboard
  showRequestHeader={true}
  showResponseHeader={true}
/>

⚠️ Important:
If you enable draggable, enableDeviceShake, or useCopyToClipboard without installing the corresponding peer dependency, the debugger will throw a descriptive error at runtime, guiding you to install the required package.

📚 API Reference

NetworkLoggerOverlay

The main UI component that displays the network logs with a draggable floating button interface.

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | networkLogger | NetworkLogger | Required | The network logger instance | | enableDeviceShake | boolean | false | Enable shake-to-show/hide functionality (requires react-native-shake) | | draggable | boolean | false | Enable draggable floating button (requires react-native-gesture-handler and react-native-reanimated) | | useCopyToClipboard | boolean | false | Enable copy to clipboard (requires @react-native-clipboard/clipboard) | | showRequestHeader | boolean | false | Display request headers in log details | | showResponseHeader | boolean | false | Display response headers in log details |

Usage Examples

// Minimal setup
<NetworkLoggerOverlay networkLogger={networkLogger} />

// With device shake support (if installed)
<NetworkLoggerOverlay 
  networkLogger={networkLogger}
  enableDeviceShake={true}
/>

// Full-featured setup (requires peer dependencies)
<NetworkLoggerOverlay 
  networkLogger={networkLogger}
  enableDeviceShake={true}
  draggable={true}
  useCopyToClipboard={true}
  showRequestHeader={true}
  showResponseHeader={true}
/>

NetworkLogger

The core logger instance that handles request interception and storage.

Methods

| Method | Description | |--------|-------------| | setupInterceptor() | Initialize network request interception | | clearLogs() | Clear all stored network logs | | getLogs() | Get array of all stored network logs |

🛠️ Usage Patterns

Development vs Production

import { networkLogger, NetworkLoggerOverlay } from 'react-native-api-debugger';

export default function App() {
  useEffect(() => {
    // Only enable in development
    if (__DEV__) {
      networkLogger.setupInterceptor();
    }
  }, []);

  return (
    <View style={{ flex: 1 }}>
      {/* Your app content */}
      
      {/* Only show in development */}
      {__DEV__ && (
        <NetworkLoggerOverlay 
          networkLogger={networkLogger}
          enableDeviceShake={true}
          draggable={true}
          useCopyToClipboard={true}
        />
      )}
    </View>
  );
}

🎯 TypeScript Support

The package includes comprehensive TypeScript definitions:

import type { 
  NetworkLog, 
  NetworkResponse, 
  NetworkRequestHeaders,
  LogListener,
  NetworkLoggerConfig
} from 'react-native-api-debugger';

// Example: Custom log processing
const processNetworkLogs = (logs: NetworkLog[]) => {
  const failedRequests = logs.filter(log => 
    log.response && log.response.status >= 400
  );
  
  console.log(`Found ${failedRequests.length} failed requests`);
};

🔧 Troubleshooting

Common Issues

TypeScript Errors

// Ensure correct imports for types
import type { NetworkLog } from 'react-native-api-debugger';

Gesture Handler Setup

// Make sure to wrap your app with GestureHandlerRootView for draggable functionality
import { GestureHandlerRootView } from 'react-native-gesture-handler';

export default function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      {/* Your app content */}
    </GestureHandlerRootView>
  );
}

Performance Considerations

• Memory Management: The logger automatically limits stored requests to prevent memory issues (default: 100 requests)
• Production Builds: Always disable in production to avoid performance impact
• Large Responses: Consider filtering or truncating large response bodies

Production Safety

// Environment-based configuration
const isDev = __DEV__;
const isStaging = process.env.NODE_ENV === 'staging';

const showLogger = isDev || isStaging;

export default function App() {
  useEffect(() => {
    if (showLogger) {
      networkLogger.setupInterceptor();
    }
  }, []);

  return (
    <View style={{ flex: 1 }}>
      {/* Your app content */}
      {showLogger && (
        <NetworkLoggerOverlay networkLogger={networkLogger} />
      )}
    </View>
  );
}

🤝 Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Clone your fork: git clone https://github.com/cmcWebCode40/react-native-api-debugger.git
3. Install dependencies: npm install
4. Create a feature branch: git checkout -b feature/amazing-feature
5. Make your changes and add tests
6. Run tests: npm test
7. Commit changes: git commit -m 'Add amazing feature'
8. Push to branch: git push origin feature/amazing-feature
9. Open a Pull Request

Development Setup

# Clone the repository
git clone https://github.com/cmcWebCode40/react-native-api-debugger.git

# Install dependencies
cd react-native-api-debugger
npm install

# Run tests
npm test

# Start the example app
cd example
npm install
npx react-native run-ios # or run-android

📄 License

MIT License - see the LICENSE file for details.

🆘 Support & Community

• 🐛 Bug Reports: GitHub Issues
• 💡 Feature Requests: GitHub Discussions
• 📖 Documentation: Wiki
• 💬 Community: Discord Server
• 🐦 Updates: @YourTwitter

📊 Stats & Recognition

Made with ❤️ for the React Native community

Built with create-react-native-library