React Native API Debugger

A comprehensive network debugging tool for React Native applications. Monitor, inspect, and debug HTTP requests and WebSocket connections with a unified tabbed overlay interface.

Features

HTTP Debugging

• Network Interception - Automatically captures all fetch() and XMLHttpRequest calls
• Request Details - View headers, body, response, timing, and status codes
• cURL Export - Copy requests as cURL commands
• Advanced Filtering - Filter by status code (2xx, 3xx, 4xx, 5xx), search by URL/method/body
• Export Logs - Export to HAR, Postman Collection, or JSON formats
• Request Replay - Re-execute captured requests with optional modifications
• Slow Request Detection - Visual indicator for requests exceeding threshold
• Sensitive Data Redaction - Detect and mask sensitive headers and body fields

WebSocket Debugging

• WebSocket Interception - Automatically captures all WebSocket connections
• Connection Monitoring - Track connection state (connecting, open, closing, closed)
• Message Logging - View sent and received messages with timestamps
• Message Filtering - Filter by direction (sent/received) or search by content
• Binary Support - Handles text and binary message types
• Connection Metrics - Track message counts, bytes transferred, and connection duration
• Live Indicators - Visual indicators for active connections

General

• Unified Interface - Tabbed modal with HTTP and WebSocket views
• Draggable Overlay - Floating button that can be positioned anywhere on screen
• Dark/Light Theme - Toggle between themes
• Individual Log Deletion - Remove specific entries without clearing all logs
• Device Shake Support - Shake to show/hide the debugger
• TypeScript Support - Full type definitions included

Installation

npm install react-native-api-debugger

# or
yarn add react-native-api-debugger

Optional Peer Dependencies

Install only what you need:

| Package | Required For | |---------|--------------| | react-native-svg (Recommended) | SVG icons (falls back to text icons) | | react-native-gesture-handler | Draggable floating button | | react-native-reanimated | Smooth drag animations | | react-native-shake | Device shake detection | | @react-native-clipboard/clipboard | Copy to clipboard |

# For draggable button
npm install react-native-gesture-handler react-native-reanimated

# For device shake
npm install react-native-shake

# For clipboard
npm install @react-native-clipboard/clipboard

# For SVG icons (optional - text fallback available)
npm install react-native-svg

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

Quick Setup

1. Basic Usage (HTTP Only)

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 */}
      
      <NetworkLoggerOverlay
        networkLogger={networkLogger}
        draggable={false}
        enableDeviceShake={false}
        useCopyToClipboard={false}
      />
    </View>
  );
}

2. Full Setup (HTTP + WebSocket)

Use NetworkLoggerOverlay with enableWebSocket={true} for the unified tabbed interface.

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

export default function App() {
  useEffect(() => {
    // Setup HTTP interceptor
    networkLogger.setupInterceptor();
    
    // Setup WebSocket interceptor
    webSocketLogger.setupInterceptor();
  }, []);

  return (
    <View style={{ flex: 1 }}>
      {/* Your app content */}
      
      <NetworkLoggerOverlay
        networkLogger={networkLogger}
        webSocketLogger={webSocketLogger}
        enableWebSocket={true}
        draggable={false}
      />
    </View>
  );
}

3. With Draggable Button

Requires react-native-gesture-handler and react-native-reanimated.

import { GestureHandlerRootView } from 'react-native-gesture-handler';
import { 
  networkLogger, 
  webSocketLogger, 
  NetworkLoggerOverlay 
} from 'react-native-api-debugger';

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

  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      {/* Your app content */}
      
      <NetworkLoggerOverlay
        networkLogger={networkLogger}
        webSocketLogger={webSocketLogger}
        enableWebSocket={true}
        draggable={true}
      />
    </GestureHandlerRootView>
  );
}

4. Full Featured Setup

<NetworkLoggerOverlay
  networkLogger={networkLogger}
  webSocketLogger={webSocketLogger}
  enableWebSocket={true}
  draggable={true}
  enableDeviceShake={true}
  useCopyToClipboard={true}
  showRequestHeader={true}
  showResponseHeader={true}
  theme="dark"
  onThemeChange={(theme) => console.log('Theme:', theme)}
/>

Advanced Usage

Configuration Options

Configure the interceptor with custom settings:

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

useEffect(() => {
  networkLogger.configure({
    maxLogs: 50,                      // Maximum logs to store (default: 100)
    ignoredUrls: ['/health', '/ping'], // URL patterns to ignore
    ignoredDomains: ['analytics.example.com'],
    ignoredMethods: ['OPTIONS'],       // HTTP methods to ignore
    slowRequestThreshold: 2000,        // Mark requests slower than 2s
  });
  
  networkLogger.setupInterceptor();
}, []);

NetworkLogger Methods

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

// Initialize interception
networkLogger.setupInterceptor();

// Get all logs
const logs = networkLogger.getLogs();

// Get log count
const count = networkLogger.getLogCount();

// Clear all logs
networkLogger.clearLogs();

// Delete a specific log
networkLogger.deleteLog(logId);

// Enable/disable logging
networkLogger.enable();
networkLogger.disable();

// Check if enabled
const isEnabled = networkLogger.isLoggerEnabled();

// Update configuration
networkLogger.configure({ maxLogs: 200 });

// Get current configuration
const config = networkLogger.getConfig();

Subscribe to Log Changes

useEffect(() => {
  const unsubscribeHttp = networkLogger.subscribe((logs) => {
    console.log('HTTP logs updated:', logs.length);
  });
  
  const unsubscribeWs = webSocketLogger.subscribe((logs) => {
    console.log('WebSocket logs updated:', logs.length);
  });
  
  return () => {
    unsubscribeHttp();
    unsubscribeWs();
  };
}, []);

Export Utilities

import { exportToHAR, exportToPostman, exportLogs } from 'react-native-api-debugger';

const logs = networkLogger.getLogs();

// Export to HAR format (for browser DevTools)
const harContent = exportToHAR(logs);

// Export to Postman Collection
const postmanContent = exportToPostman(logs, 'My API Collection');

// Export to JSON
const jsonContent = exportLogs(logs, 'json');

Request Replay

import { replayRequest, canReplayRequest, getReplayWarnings } from 'react-native-api-debugger';

const log = networkLogger.getLogs()[0];

// Check if request can be replayed
if (canReplayRequest(log)) {
  // Get warnings (e.g., "This request may modify data")
  const warnings = getReplayWarnings(log);
  
  // Replay with optional modifications
  const result = await replayRequest(log, {
    modifyHeaders: { 'Authorization': 'Bearer new-token' },
    timeout: 5000,
  });
  
  if (result.success) {
    console.log('Response:', result.response);
  }
}

Sensitive Data Detection

import { detectSensitiveData, redactNetworkLog } from 'react-native-api-debugger';

const log = networkLogger.getLogs()[0];

// Check for sensitive data
const info = detectSensitiveData(log);
if (info.hasSensitiveHeaders) {
  console.log('Contains sensitive headers');
}

// Redact sensitive data before sharing
const redactedLog = redactNetworkLog(log, { enabled: true });

cURL Generation

import { generateCurl } from 'react-native-api-debugger';

const log = networkLogger.getLogs()[0];
const curlCommand = generateCurl(log);
// curl -X POST 'https://api.example.com/users' -H 'Content-Type: application/json' -d '{"name":"John"}'

WebSocket Logger Methods

import { webSocketLogger } from 'react-native-api-debugger';

// Initialize interception
webSocketLogger.setupInterceptor();

// Configure options
webSocketLogger.configure({
  maxConnections: 50,           // Maximum connections to store
  captureMessages: true,        // Log individual messages
  maxMessagesPerConnection: 100, // Max messages per connection
  ignoredUrls: ['*/health'],    // URL patterns to ignore
});

// Get all logs
const logs = webSocketLogger.getLogs();

// Get log count
const count = webSocketLogger.getLogCount();

// Clear all logs
webSocketLogger.clearLogs();

// Delete a specific log
webSocketLogger.deleteLog(logId);

// Close an active connection
webSocketLogger.closeConnection(logId);

// Enable/disable logging
webSocketLogger.enable();
webSocketLogger.disable();

// Get active connections count
const activeCount = webSocketLogger.getActiveConnectionsCount();

// Restore original WebSocket (remove interception)
webSocketLogger.restoreInterceptor();

API Reference

NetworkLoggerOverlay Props

The unified overlay component with HTTP and optional WebSocket tabs.

| Prop | Type | Default | Description | |------|------|---------|-------------| | networkLogger | NetworkLogger | Required | HTTP logger instance | | webSocketLogger | WebSocketLogger | - | WebSocket logger instance (required if enableWebSocket is true) | | enabled | boolean | __DEV__ | Enable/disable the overlay | | enableWebSocket | boolean | false | Enable WebSocket debugging tab | | draggable | boolean | false | Enable draggable button | | enableDeviceShake | boolean | false | Show on device shake | | useCopyToClipboard | boolean | false | Enable clipboard copy | | showRequestHeader | boolean | false | Show request headers | | showResponseHeader | boolean | false | Show response headers | | theme | 'light' \| 'dark' | 'dark' | Color theme | | onThemeChange | (theme) => void | - | Theme change callback |

NetworkLoggerConfig

| Option | Type | Default | Description | |--------|------|---------|-------------| | maxLogs | number | 100 | Maximum logs to store | | ignoredUrls | string[] | [] | URL patterns to ignore | | ignoredDomains | string[] | [] | Domains to ignore | | ignoredMethods | string[] | [] | HTTP methods to ignore | | redactHeaders | string[] | ['Authorization', ...] | Headers to redact | | enableRedaction | boolean | false | Enable auto-redaction | | slowRequestThreshold | number | 3000 | Slow request threshold (ms) |

NetworkLog Type

interface NetworkLog {
  id: number;
  method: string;
  url: string;
  headers: Record<string, string>;
  body: string | null;
  timestamp: string;
  startTime: number;
  response?: {
    status: number;
    statusText: string;
    headers: Record<string, string>;
    body: string;
    duration: number;
  };
  error?: string;
  duration?: number;
  isSlow?: boolean;
  bookmarked?: boolean;
}

WebSocketLog Type

interface WebSocketLog {
  id: number;
  url: string;
  state: 'connecting' | 'open' | 'closing' | 'closed';
  protocols?: string[];
  connectTime: string;
  openTime?: string;
  closeTime?: string;
  closeCode?: number;
  closeReason?: string;
  error?: string;
  handshakeDuration?: number;
  messages: WebSocketMessage[];
  messageCount: { sent: number; received: number };
  bytesReceived: number;
  bytesSent: number;
}

interface WebSocketMessage {
  id: number;
  direction: 'sent' | 'received';
  data: string;
  dataType: 'text' | 'binary';
  timestamp: string;
  size: number;
}

WebSocketLoggerConfig

| Option | Type | Default | Description | |--------|------|---------|-------------| | maxConnections | number | 100 | Maximum connections to store | | captureMessages | boolean | true | Log individual messages | | maxMessagesPerConnection | number | 100 | Max messages per connection | | ignoredUrls | string[] | [] | URL patterns to ignore |

Production Safety

The overlay is disabled by default in production (enabled defaults to __DEV__). To explicitly control:

<NetworkLoggerOverlay
  networkLogger={networkLogger}
  enabled={__DEV__}  // Only in development
/>

For staging environments:

const showDebugger = __DEV__ || process.env.STAGING === 'true';

<NetworkLoggerOverlay
  networkLogger={networkLogger}
  enabled={showDebugger}
/>

Troubleshooting

Draggable button not working

Ensure your app is wrapped with GestureHandlerRootView:

import { GestureHandlerRootView } from 'react-native-gesture-handler';

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

Share sheet not appearing

The share sheet requires the main modal to close first. This is handled automatically - ensure you're using the latest version.

Requests not being captured

Make sure setupInterceptor() is called before any network requests:

useEffect(() => {
  networkLogger.setupInterceptor();
  webSocketLogger.setupInterceptor();
}, []); // Empty dependency array - runs once on mount

WebSocket connections not appearing

Ensure you have:

1. Called webSocketLogger.setupInterceptor() before any WebSocket connections
2. Set enableWebSocket={true} on the NetworkLoggerOverlay
3. Passed the webSocketLogger prop

<NetworkLoggerOverlay
  networkLogger={networkLogger}
  webSocketLogger={webSocketLogger}
  enableWebSocket={true}  // Required to show WebSocket tab
  draggable={true}
/>

Setup error messages

The debugger will throw helpful error messages if interceptors aren't initialized:

• HTTP: If networkLogger.setupInterceptor() wasn't called before rendering
• WebSocket: If enableWebSocket={true} but webSocketLogger.setupInterceptor() wasn't called

These errors include code examples to help you fix the issue quickly.

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make changes and run tests: yarn test
4. Commit: git commit -m 'Add my feature'
5. Push: git push origin feature/my-feature
6. Open a Pull Request

Development

git clone https://github.com/cmcWebCode40/react-native-api-debugger.git
cd react-native-api-debugger
yarn install

# Run example app
cd example
yarn install
yarn ios  # or yarn android

License

MIT License - see LICENSE for details.

Support

• Bug Reports: GitHub Issues
• Feature Requests: GitHub Discussions