React Native Debug Console

A floating debug console for React Native / Expo apps. Captures console logs, errors, and warnings with a beautiful overlay UI.

Perfect for debugging production builds and sharing logs with your team.

Features

• Floating debug button with error count badge
• Full-screen modal console with all captured logs
• Color-coded log entries (error, warning, info, log)
• Share logs functionality
• Fully customizable colors and positioning
• Environment variable support for enabling/disabling
• Zero external dependencies (optional react-native-svg)
• TypeScript support
• Works with Expo and bare React Native

Installation

# Using npm
npm install @zizwar/react-native-debug-console

# Using yarn
yarn add @zizwar/react-native-debug-console

# Using pnpm
pnpm add @zizwar/react-native-debug-console

Quick Start

Wrap your app with the DebugConsole component:

import { DebugConsole } from '@zizwar/react-native-debug-console';

export default function App() {
  return (
    <DebugConsole>
      <YourApp />
    </DebugConsole>
  );
}

That's it! A floating bug button will appear in the corner of your app. Tap it to see all console logs.

Configuration

Using Environment Variables

import { DebugConsole } from '@zizwar/react-native-debug-console';

export default function App() {
  return (
    <DebugConsole
      config={{
        // Enable based on environment variable
        enabled: process.env.EXPO_PUBLIC_DEBUG === 'true',
        appName: 'MyApp',
      }}
    >
      <YourApp />
    </DebugConsole>
  );
}

In your .env file:

EXPO_PUBLIC_DEBUG=true

Full Configuration Options

import { DebugConsole, DebugConsoleConfig } from '@zizwar/react-native-debug-console';

const config: DebugConsoleConfig = {
  // Enable or disable (default: true)
  enabled: true,

  // Max logs to keep (default: 100)
  maxLogs: 100,

  // App name for sharing (default: 'App')
  appName: 'MyApp',

  // Capture specific log types (all default to true)
  captureLog: true,
  captureWarn: true,
  captureError: true,
  captureInfo: true,

  // Custom colors
  colors: {
    background: '#1a1a2e',
    surface: '#2a2a3e',
    text: '#ffffff',
    textSecondary: '#888888',
    error: '#FF5252',
    warning: '#FFD740',
    info: '#40C4FF',
    log: '#888888',
    buttonBackground: '#FF6B6B',
    buttonIcon: '#ffffff',
  },

  // Button position
  buttonPosition: {
    bottom: 100,
    right: 20,
  },
};

export default function App() {
  return (
    <DebugConsole config={config}>
      <YourApp />
    </DebugConsole>
  );
}

Advanced Usage

Using HOC (Higher-Order Component)

import { withDebugConsole } from '@zizwar/react-native-debug-console';

function App() {
  return <YourApp />;
}

export default withDebugConsole(App, {
  enabled: __DEV__,
  appName: 'MyApp',
});

Manual Control with Hook

import { DebugProvider, useDebugConsole, DebugButton, DebugOverlay } from '@zizwar/react-native-debug-console';

function MyComponent() {
  const { logs, showConsole, hideConsole, clearLogs, addLog } = useDebugConsole();

  // Manually add a log
  const handlePress = () => {
    addLog('info', 'Button pressed!');
  };

  return (
    <Button onPress={handlePress} title="Press me" />
  );
}

// In your App.tsx
export default function App() {
  return (
    <DebugProvider config={{ enabled: true }}>
      <YourApp />
      <DebugButton />
      <DebugOverlay />
    </DebugProvider>
  );
}

Hide Floating Button

<DebugConsole showButton={false}>
  <YourApp />
</DebugConsole>

Custom Button or Overlay

import { DebugConsole, useDebugConsole } from '@zizwar/react-native-debug-console';

const CustomButton = () => {
  const { toggleVisibility, logs } = useDebugConsole();
  const errorCount = logs.filter(l => l.type === 'error').length;

  return (
    <TouchableOpacity onPress={toggleVisibility}>
      <Text>Debug ({errorCount} errors)</Text>
    </TouchableOpacity>
  );
};

export default function App() {
  return (
    <DebugConsole customButton={CustomButton}>
      <YourApp />
    </DebugConsole>
  );
}

API Reference

Components

| Component | Description | |-----------|-------------| | DebugConsole | Main wrapper component | | DebugProvider | Context provider (for manual setup) | | DebugButton | Floating action button | | DebugOverlay | Full-screen log viewer modal |

Hooks

| Hook | Description | |------|-------------| | useDebugConsole() | Access debug context (throws if not in provider) | | useDebugConsoleOptional() | Access debug context (returns null if not in provider) |

Context Values (from useDebugConsole)

interface DebugConsoleContextType {
  logs: LogEntry[];
  isVisible: boolean;
  config: DebugConsoleConfig;
  addLog: (type: LogType, message: string, data?: any) => void;
  clearLogs: () => void;
  toggleVisibility: () => void;
  showConsole: () => void;
  hideConsole: () => void;
}

Types

type LogType = 'log' | 'warn' | 'error' | 'info';

interface LogEntry {
  id: string;
  timestamp: Date;
  type: LogType;
  message: string;
  data?: any;
}

Environment Variables for Expo

Add to your .env file:

# Enable debug console
EXPO_PUBLIC_DEBUG=true

Then use in your app:

<DebugConsole
  config={{
    enabled: process.env.EXPO_PUBLIC_DEBUG === 'true',
  }}
>

Tips

1. Production builds: Set enabled: false in production, or use environment variables
2. Performance: The console keeps only the last 100 logs by default to prevent memory issues
3. Sharing: Logs can be shared via the native Share API for easy debugging
4. Custom styling: All colors are customizable to match your app's theme

License

MIT

Contributing

Contributions are welcome! Please open an issue or submit a pull request.