@lokal-dev/react-native-bugbubble - React Native In-App DevTools

@lokal-dev/react-native-bugbubble is a powerful in-app debugging tool for React Native applications. Monitor network requests, WebSocket events, console logs, and analytics events in real-time with a beautiful, draggable UI. Perfect for debugging React Native apps without external tools.

Supported Log Types

This library currently supports logging for the following:

• ✅ Network Requests: Automatically intercepts all network calls.
• ✅ Console Logs: Automatically intercepts all console methods (log, debug, info, warn, error)
• ✅ WebSocket Events: Automatically intercepts WebSocket connections and events (open, message, close, error)
• ✅ Analytics Events: Requires explicit logging using BugBubbleLogger.logAnalytics()

Features

• ✅ Automatic Interception: Network requests, WebSocket events, and console logs are automatically captured without any additional code
• ✅ Explicit Logging API: Manual logging methods available for all log types (useful for custom scenarios or analytics)
• ✅ Real-Time Monitoring: View logs as they happen in UI
• ✅ Draggable Floating Button: Drag the floating button anywhere on the screen for easy access
• ✅ Search & Filter: Powerful search functionality across all log types
• ✅ TypeScript Support: Full TypeScript definitions included
• ✅ Selective Tracking: Disable specific log types to reduce overhead and customize your debugging experience

Demo

Installation

npm install @lokal-dev/react-native-bugbubble
# or
yarn add @lokal-dev/react-native-bugbubble
# or
pnpm add @lokal-dev/react-native-bugbubble

No peer dependencies required! This library is pure JavaScript/TypeScript and only requires React Native.

Quick Start

Add the BugBubble component to your app's root component:

import { BugBubble } from '@lokal-dev/react-native-bugbubble';

export default function App() {
  return (
    <>
      <YourAppContent />
      <BugBubble />
    </>
  );
}

That's it! A floating button will appear on your screen. Tap it to open the debugger, or drag it to reposition it.

For configuration options, see the Configuration section.

Usage

Explicit Logging API

Use the BugBubbleLogger API for manual event logging:

import { BugBubbleLogger } from '@lokal-dev/react-native-bugbubble';

Log Analytics Events

// Log an analytics event
BugBubbleLogger.logAnalytics('user_login', {
  userId: '123',
  method: 'email',
  timestamp: Date.now(),
});

Log Network Requests Manually

// Log a network request explicitly
BugBubbleLogger.logNetwork(
  'POST',
  'https://api.example.com/users',
  201, // status code
  { 'Content-Type': 'application/json' }, // request headers
  { 'Content-Type': 'application/json' }, // response headers
  { name: 'John Doe' }, // request body
  { id: 1, name: 'John Doe' }, // response body
  150 // duration in milliseconds
);

Log WebSocket Events Manually

// Log a WebSocket event
BugBubbleLogger.logWebSocket('message', 'wss://api.example.com/ws', {
  type: 'ping',
  data: 'hello',
});

Log Console Messages Manually

// Log console messages explicitly
BugBubbleLogger.logConsole('info', 'User logged in', { userId: '123' });
BugBubbleLogger.logConsole('error', 'Failed to fetch data', error);
BugBubbleLogger.logConsole('warn', 'Deprecated API used');

Configuration

All configuration options are completely optional. The library works with sensible defaults out of the box. See the API Reference section for all available options and their defaults.

import { BugBubble } from '@lokal-dev/react-native-bugbubble';

// Minimal setup
<BugBubble />

// Customize with config
<BugBubble
  config={{
    maxLogs: 1000,
    floatingButtonPosition: {
      top: 100,
      right: 20,
    },
    trackingOptions: {
      enabled: true,
      options: {
        analytics: true,
        network: true,
        websocket: true,
        console: true,
      },
    },
  }}
/>

Note: Configuration is set once when the component mounts and cannot be changed at runtime. To change configuration, remount the component with new props.

Disabling Tracking

You can disable tracking for specific log types or disable all tracking:

// Disable network tracking only
<BugBubble
  config={{
    trackingOptions: {
      enabled: true,
      options: {
        network: false,
      },
    },
  }}
/>

// Disable all tracking (button will also be hidden)
<BugBubble
  config={{
    trackingOptions: {
      enabled: false,
    },
  }}
/>

When tracking is disabled:

• If trackingOptions.enabled is false: All tracking is disabled and the floating button is hidden
• If a specific log type is disabled: The corresponding tab is hidden, the interceptor won't start, and no logs will be collected for that type

API Reference

BugBubble

Root component that renders the debugger UI. Should be added at the root level of your app.

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | config | Partial<BugBubbleConfig> | undefined | Optional configuration object. See config options below. |

Config Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | maxLogs | number | 1000 | Maximum number of logs to store in memory. | | floatingButtonPosition | { top: number, right: number } | { top: 100, right: 20 } | Initial position of the floating button. top and right are distances from top and right edges in pixels. | | trackingOptions | object | undefined | Options to control tracking behavior. See nested options below. |

trackingOptions Properties

| Property | Type | Default | Description | |----------|------|---------|-------------| | enabled | boolean | true | Master switch for all tracking and button visibility. | | options | object | undefined | Options to enable/disable specific log types. See nested options below. |

trackingOptions.options Properties

| Property | Type | Default | Description | |----------|------|---------|-------------| | analytics | boolean | true | Enable/disable analytics tracking. | | network | boolean | true | Enable/disable network tracking. | | websocket | boolean | true | Enable/disable WebSocket tracking. | | console | boolean | true | Enable/disable console tracking. |

BugBubbleLogger

Explicit logging API for manual event logging.

logAnalytics(eventName, properties?)

Log an analytics event.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | eventName | string | Yes | Name of the analytics event. | | properties | object | No | Event properties as key-value pairs. |

logNetwork(method, url, statusCode?, requestHeaders?, responseHeaders?, requestBody?, responseBody?, duration?)

Log a network request manually.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | method | string | Yes | HTTP method (GET, POST, PUT, DELETE, etc.). | | url | string | Yes | Request URL. | | statusCode | number | No | Response status code. | | requestHeaders | object | No | Request headers as key-value pairs. | | responseHeaders | object | No | Response headers as key-value pairs. | | requestBody | any | No | Request body. | | responseBody | any | No | Response body. | | duration | number | No | Request duration in milliseconds. |

logWebSocket(event, url?, data?)

Log a WebSocket event manually.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | event | string | Yes | Event type: 'open', 'message', 'close', or 'error'. | | url | string | No | WebSocket URL. | | data | any | No | Event data. |

logConsole(level, ...args)

Log a console message manually.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | level | string | Yes | Log level: 'debug', 'info', 'warn', or 'error'. | | ...args | any[] | Yes | Arguments to log (same as console methods). |

Troubleshooting

Debugger Not Appearing

• Ensure you've added <BugBubble /> component to root level of your app
• Verify that trackingOptions.enabled is set to true in config (see API Reference)

Logs Not Appearing

• Ensure the debugger component is mounted before making network requests
• Check that interceptors are started (they start automatically when component mounts)
• Check if the log type is disabled in trackingOptions configuration (see Configuration)

Example

Check out the example directory for a comprehensive demo of all features.

Author

• Shivangi - [email protected]

License

MIT

Support

For issues, questions, or contributions, please open an issue on the GitHub repository.