rnbugkit-sdk

Lightweight crash reporting and network monitoring SDK for React Native.

rnbugkit-sdk captures uncaught errors, render-time exceptions, unhandled promise rejections, and network failures in your app — along with rich context (recent screens, user actions, device info) — and ships them to the RNBugKit backend. It does not collect request or response bodies.

• Zero native setup — pure JS, works with any RN 0.70+ project
• Auto crash capture — sync errors, async errors, render errors, unhandled rejections
• Network monitoring — fetch + XMLHttpRequest, failures and slow requests
• Breadcrumbs — navigation history and user action trail attached to every report
• Offline queue — reports queued and retried when connectivity returns
• Privacy-first — no request/response bodies, configurable key redaction, opt-out in dev

Install

npm install rnbugkit-sdk
# or
yarn add rnbugkit-sdk

Optional, for persistent offline queue across app restarts:

npm install @react-native-async-storage/async-storage

Quick start

Initialize the SDK as early as possible — ideally in index.js, before AppRegistry.registerComponent:

// index.js
import { AppRegistry } from 'react-native';
import { BugKit } from 'rnbugkit-sdk';
import App from './App';
import { name as appName } from './app.json';

BugKit.init({
  apiKey: 'your_api_key',
  appVersion: '1.0.0',
});

AppRegistry.registerComponent(appName, () => App);

That's it. From this point on, every uncaught exception, unhandled promise rejection, and failed/slow network request is captured automatically.

Configuration

BugKit.init({
  apiKey: 'your_api_key',      // required
  appVersion: '1.0.0',         // required

  // Optional — defaults shown
  enabled: true,               // master switch
  enabledInDev: false,         // capture in __DEV__ builds
  slowRequestThreshold: 3000,  // ms — requests slower than this are reported
  flushInterval: 30000,        // ms — network batch flush cadence
  redactedKeys: ['password', 'token', 'secret', 'card', 'cvv', 'pin'],
  persistQueue: false,         // persist offline queue via AsyncStorage
  sampleRate: 1,               // 0..1 — fraction of crashes to report
  dedupWindowMs: 30000,        // suppress identical crashes within this window
  onBeforeSend: (payload) => payload, // mutate or drop a report before send
});

Config reference

| Option | Type | Default | Description | |---|---|---|---| | apiKey | string | — | Your RNBugKit project key. Required. | | appVersion | string | — | Attached to every report. Required. | | enabled | boolean | true | Master switch. When false, init is a no-op. | | enabledInDev | boolean | false | Capture in __DEV__ builds. Off by default so the RedBox isn't shadowed. | | slowRequestThreshold | number | 3000 | Any request taking longer than this (ms) is reported as slow. | | flushInterval | number | 30000 | How often (ms) batched network stats/failures are flushed. | | redactedKeys | string[] | see below | Keys (case-insensitive substring match) redacted from context and screenState. | | persistQueue | boolean | false | Persist the offline queue across app launches. Requires @react-native-async-storage/async-storage. | | sampleRate | number | 1 | Probability (0..1) that a crash is emitted. | | dedupWindowMs | number | 30000 | Same crash (by stack hash) within this window is folded into repeated_count. | | onBeforeSend | (p) => p \| null | identity | Inspect/mutate/drop a payload right before send. Return null to drop. |

Default redactedKeys: password, token, secret, card, cvv, pin.

API

Crashes & manual reports

// One-off manual report (no Error needed)
BugKit.reportManually('User said the camera froze');

// Log a message at a level
BugKit.captureMessage('Cache miss for user profile', 'warning');

// Log a caught exception
try {
  await fetchProfile();
} catch (e) {
  BugKit.captureException(e as Error);
}

Breadcrumbs

// Track screen transitions (keeps the last 5)
BugKit.onNavigationStateChange({ name: 'CheckoutScreen' });

// Track user actions (keeps the last 10)
BugKit.recordAction('tap', 'submitButton');
BugKit.recordAction('scroll', 'productList');
BugKit.recordAction('navigate', 'Profile');
BugKit.recordAction('shake');
BugKit.recordAction('submit', 'loginForm');
BugKit.recordAction('focus', 'emailInput');

Context & screen state

// Persistent context — included on every report until cleared
BugKit.setContext({ userId: 'u_123', plan: 'pro' });
BugKit.clearContext();

// Snapshot of the current screen — overwritten on each call
BugKit.setScreenState({ tab: 'orders', filter: 'pending' });

Both context and screenState are redacted using redactedKeys before sending.

Cleanup

// Restore original handlers, clear in-memory queue, drop config
BugKit.destroy();

You usually don't need this — call only when wholly disabling the SDK at runtime.

Components & hooks

<BugKitBoundary>

A React error boundary that captures render-time exceptions and forwards them to the backend.

import { BugKitBoundary } from 'rnbugkit-sdk';

<BugKitBoundary
  fallback={(error) => <ErrorScreen message={error.message} />}
  onError={(error, info) => console.log(error)}
>
  <App />
</BugKitBoundary>

| Prop | Type | Notes | |---|---|---| | fallback | ReactNode \| (error: Error) => ReactNode | Rendered when a child throws. | | onError | (error, info) => void | Called in addition to the automatic report. |

Wrap your screens or feature roots — granular boundaries give better UX than a single top-level one.

<BugKitTouchBoundary>

Wraps a subtree and automatically records recordAction("tap", label) for every interactive press. The label is taken from testID → accessibilityLabel → component display name (TouchableOpacity, Pressable, etc.).

import { BugKitTouchBoundary } from 'rnbugkit-sdk';

<BugKitTouchBoundary>
  <App />
</BugKitTouchBoundary>

| Prop | Type | Default | Notes | |---|---|---|---| | disabled | boolean | false | Turn off without unmounting. | | ignoreNames | string[] | [] | Display names to skip (e.g. ['DebugButton']). | | dedupeWindowMs | number | 300 | Same label within this window is recorded once. | | maxDepth | number | 20 | How far up the fiber tree to walk looking for a label. |

Touch instrumentation never throws — failures are swallowed silently so it can't break your app.

<ReportBugButton>

Floating button with a modal that lets users describe a bug and submit it.

import { ReportBugButton } from 'rnbugkit-sdk';

<ReportBugButton
  label="Report bug"
  placeholder="What went wrong?"
  onReported={(success, description) => console.log({ success })}
/>

| Prop | Type | Default | |---|---|---| | label | string | "Report bug" | | placeholder | string | "What went wrong?" | | submitLabel | string | "Send" | | cancelLabel | string | "Cancel" | | onPress | () => void | opens modal | | onReported | (ok, description) => void | — | | style, textStyle | — | override styling |

useReportBug()

Hook for custom reporting UIs.

import { useReportBug } from 'rnbugkit-sdk';

function Feedback() {
  const { report, isReporting, lastError } = useReportBug();
  return (
    <Button
      title={isReporting ? 'Sending…' : 'Send feedback'}
      onPress={() => report('Feedback text here')}
      disabled={isReporting}
    />
  );
}

What gets captured

Every bug report includes:

• title, stack_trace, kind (crash | manual | message), level
• app_version, occurred_at
• device_info — platform, OS version, screen size, RN version, is_dev
• navigation_history — last 5 screens
• user_actions — last 10 actions (tap/scroll/navigate/shake/submit/focus)
• component_state — last setScreenState value (redacted)
• context — setContext values (redacted)
• repeated_count — when deduplication folds in repeats

Network monitoring captures only metadata:

• url, method, status_code, duration_ms, failure_type, error_message

Failure types: error_status (4xx/5xx), timeout, no_connection, slow.

Aggregated stats (count, error count, avg/max duration) are computed per endpoint per hour and shipped in batches.

Privacy

rnbugkit-sdk is built to minimize what leaves the device:

• No request bodies, no response bodies, no headers. Network monitoring records the URL, method, status, and timing — nothing more.
• No PII collected by default. No user IDs, no emails, no device IDs. Anything in context / screenState is yours to populate.
• Redaction. context and screenState keys matching redactedKeys (case-insensitive substring) are replaced with [REDACTED].
• onBeforeSend escape hatch. Inspect, mutate, or drop any payload before it's sent.

Note on URLs. Query strings are captured as-is. If your endpoints encode sensitive values in the query string (e.g. ?token=…), strip them in onBeforeSend or move them to headers.

Offline queue

When the network is unavailable or the backend is unreachable, reports are queued in memory (up to 50 items, 3 retry attempts each) and retried automatically when the app returns to the foreground.

To survive app restarts, enable persistence:

BugKit.init({
  apiKey: '…',
  appVersion: '…',
  persistQueue: true,
});

This requires @react-native-async-storage/async-storage as a peer install.

Notes on dev builds

By default, the SDK is disabled in __DEV__ so the RedBox stays the source of truth while you're developing. To enable it during development (useful for testing reporting flows):

BugKit.init({
  apiKey: '…',
  appVersion: '…',
  enabledInDev: true,
});

Sync errors thrown from event handlers in dev are sometimes intercepted by Metro's RedBox before the SDK sees them — test crash flows in a release build for accurate behavior.

Sampling and deduplication

• Sampling — sampleRate: 0.1 reports ~10% of crashes. Useful at scale.
• Deduplication — same stack within dedupWindowMs is folded into a single report with repeated_count incremented.

BugKit.init({
  apiKey: '…',
  appVersion: '…',
  sampleRate: 0.25,
  dedupWindowMs: 60000,
});

License

MIT © PMI Software Systems