bugcatch-react-native-sdk

Official React Native / Expo SDK for BugCatch error tracking.

Compatible with Expo Go, Expo managed workflow, and React Native CLI - no native modules required.

Installation

npm install bugcatch-react-native-sdk
# or
yarn add bugcatch-react-native-sdk

Quick Start

Call BugCatch.init() as early as possible — before any other imports or app logic. The recommended place is your entry file (index.js or App.tsx).

// index.js (before everything else)
import BugCatch from 'bugcatch-react-native-sdk';

BugCatch.init({
  dsn: 'https://your-host/ingest/YOUR_PROJECT_ID?key=YOUR_SDK_KEY',
  release: '1.0.0',
  environment: 'production',
});

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | dsn | string | required | DSN from your BugCatch project settings | | release | string | undefined | App version, e.g. "1.2.3" | | environment | string | undefined | Deployment environment, e.g. "production" | | debug | boolean | false | Print SDK logs to the console | | maxBreadcrumbs | number | 100 | Max breadcrumbs kept in memory | | autoCaptureErrors | boolean | true | Auto-capture uncaught JS errors and unhandled promise rejections | | autoCaptureBreadcrumbs | boolean | true | Auto-capture console.warn/console.error calls and app state changes | | autoTrackRequests | boolean | false | Auto-intercept fetch() calls and send timing metrics | | trackIgnoreUrls | (string \| RegExp)[] | [] | URL patterns to exclude from request tracking | | ignoreErrors | (string \| RegExp)[] | [] | Error message patterns to drop before sending | | beforeSend | (event) => event \| false | undefined | Hook to modify or drop events before they are sent |

API

BugCatch.init(options)

Initializes the SDK. Call once. Subsequent calls are ignored with a warning.

BugCatch.init({
  dsn: '...',
  release: '2.0.0',
  environment: 'staging',
  debug: true,
});

BugCatch.captureException(error, extra?)

Captures an Error object or any value as an error event. Returns the event_id.

try {
  await loadUserData();
} catch (error) {
  BugCatch.captureException(error, { screen: 'ProfileScreen' });
}

BugCatch.captureMessage(message, level?, extra?)

Captures a plain text message as an event. level defaults to "info".

BugCatch.captureMessage('Onboarding completed', 'info', { step: 3 });

BugCatch.setUser(user) / BugCatch.clearUser()

Attaches user context to all subsequent events. Call clearUser() on logout.

// After login
BugCatch.setUser({ id: '42', email: '[email protected]', username: 'alex' });

// After logout
BugCatch.clearUser();

BugCatch.setTag(key, value)

Attaches a tag to all subsequent events.

BugCatch.setTag('plan', 'pro');
BugCatch.setTag('locale', 'en-US');

BugCatch.addBreadcrumb(crumb)

Manually adds a breadcrumb to the trail attached to the next event.

BugCatch.addBreadcrumb({
  timestamp: new Date().toISOString(),
  type: 'navigation',
  category: 'nav',
  message: 'Navigated to CheckoutScreen',
});

BugCatch.trackRequest(method, route, durationMs, statusCode)

Manually reports an API request timing. Use when autoTrackRequests is off or for custom instrumentation.

const start = Date.now();
const res = await fetch('https://api.example.com/orders');
BugCatch.trackRequest('GET', '/orders', Date.now() - start, res.status);

BugCatch.destroy()

Removes all listeners and resets the singleton. Useful for hot-reload or test teardown.

BugCatch.destroy();

Error Boundary

Wrap your app (or any subtree) with BugCatchErrorBoundary to catch React render errors.

import BugCatch, { BugCatchErrorBoundary } from 'bugcatch-react-native-sdk';
import { View, Text, Button } from 'react-native';

export default function App() {
  return (
    <BugCatchErrorBoundary
      client={BugCatch.getClient()}
      fallback={(error, reset) => (
        <View>
          <Text>Something went wrong: {error.message}</Text>
          <Button title="Try again" onPress={reset} />
        </View>
      )}
    >
      <RootNavigator />
    </BugCatchErrorBoundary>
  );
}

React Navigation Breadcrumbs

Pass a breadcrumb to BugCatch on every navigation event using the onStateChange prop:

import { NavigationContainer } from '@react-navigation/native';
import BugCatch from 'bugcatch-react-native-sdk';

<NavigationContainer
  onStateChange={(state) => {
    const route = state?.routes[state.index];
    if (route) {
      BugCatch.addBreadcrumb({
        timestamp: new Date().toISOString(),
        type: 'navigation',
        category: 'nav',
        message: `Navigated to ${route.name}`,
        data: { screen: route.name },
      });
    }
  }}
>
  {/* ... */}
</NavigationContainer>

Request Tracking

Enable automatic fetch() interception to report API timings:

BugCatch.init({
  dsn: '...',
  autoTrackRequests: true,
  // Exclude specific URLs from tracking
  trackIgnoreUrls: [/analytics\.example\.com/, 'cdn.example.com'],
});

URL paths are automatically normalised — /users/42/orders/7 becomes /users/:id/orders/:id so metrics are grouped by route template.

Filtering Events

BugCatch.init({
  dsn: '...',

  // Drop errors matching these message patterns
  ignoreErrors: [
    'Network request failed',
    /ResizeObserver loop/,
  ],

  // Modify or drop events before sending
  beforeSend(event) {
    // Scrub sensitive fields
    if (event.user?.email) {
      event.user.email = '[redacted]';
    }
    // Return false to drop the event entirely
    if (event.tags?.plan === 'internal') return false;
    return event;
  },
});

What's Captured Automatically

When autoCaptureErrors: true (default):

• Uncaught JS errors via React Native's ErrorUtils
• Unhandled promise rejections

When autoCaptureBreadcrumbs: true (default):

• console.warn and console.error calls
• App foreground/background transitions (AppState)

Every event includes:

• Stack trace with in-app frame detection
• Device context (Platform.OS, Platform.Version)
• User context, tags, and breadcrumb trail
• Release and environment

License

ISC