DebugBundle React Native

React Native SDK for DebugBundle mobile apps.

This package targets iOS and Android React Native apps. It is a mobile direct-ingestion SDK, not a browser relay host: it does not provide CORS, allowedOrigins, transportMode, or /debugbundle/browser helpers.

Status

Published implementation:

• TypeScript facade and instance client.
• Safe degraded mode when the native module is unavailable, including Expo Go.
• JS-originated event enqueueing through a native module contract.
• React error boundary helper.
• React Navigation breadcrumb helpers.
• fetch and XMLHttpRequest instrumentation with target-scoped X-DebugBundle-Trace-Id.
• JS-side bounded serialization and redaction before native queue persistence.
• Android and iOS native wrappers that delegate queueing, config/status, request capture, crash/error capture, flushing, and probe trigger activation to the native SDK foundations.
• Repository-local Android Java, Swift, and Objective-C++ wrapper tests with an enforced 80% line-coverage floor for every handwritten native bridge source.
• Clean-install React Native app smoke coverage for Android and iOS, including New Architecture codegen/autolinking.

Runtime Support

| Lane | Support | | --- | --- | | Minimum compatibility | React Native 0.76+, React 18.2+, iOS 15+, Android minSdk 23 | | Recommended production | Current stable React Native 0.86.x with Hermes and the New Architecture enabled where your app supports it | | Installed-base compatibility | React Native 0.76 through current stable, including legacy bridge apps | | Rolling CI | TypeScript/package smoke, Android bridge compile on RN 0.76.9, 0.82.1, and 0.85.3, bare iOS compatibility/current-installed-base lanes, plus Expo SDK 57 / RN 0.86 Android and iOS development builds | | Expo | Expo development builds and prebuild; Expo Go is degraded because it cannot load custom native modules |

JSC compatibility is best-effort where the selected React Native lane still supports it. Hermes is the primary tested JavaScript engine.

Install

npm install @debugbundle/sdk-react-native
cd ios && pod install

iOS autolinking resolves the DebugBundleReactNative.podspec, which depends on the native DebugBundle pod from the Swift SDK.

Android apps must enable core library desugaring because the native Android SDK uses Java APIs that require desugaring on the SDK's minimum API level:

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
        coreLibraryDesugaringEnabled true
    }
}

dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5")
}

The Expo config plugin applies this Android Gradle configuration during prebuild.

Basic Setup

import { DebugBundle } from "@debugbundle/sdk-react-native";

DebugBundle.init({
  projectToken: process.env.EXPO_PUBLIC_DEBUGBUNDLE_TOKEN,
  service: "checkout-mobile",
  environment: __DEV__ ? "development" : "production",
  releaseChannel: "app-store",
  tracePropagationTargets: ["https://api.example.com"]
});

Project tokens are write-only mobile ingestion tokens, but they are still extractable from the app binary and JS bundle. Do not treat them as a secret boundary.

Network Instrumentation

import { instrumentDebugBundleNetwork } from "@debugbundle/sdk-react-native/network";

instrumentDebugBundleNetwork({
  tracePropagationTargets: ["https://api.example.com"]
});

Trace headers are added only to relative URLs or configured first-party targets. Request and response bodies are not captured by default.

React Error Boundary

import { DebugBundleErrorBoundary } from "@debugbundle/sdk-react-native/react";

export function App() {
  return (
    <DebugBundleErrorBoundary>
      <CheckoutRoot />
    </DebugBundleErrorBoundary>
  );
}

React Navigation

import { NavigationContainer } from "@react-navigation/native";
import {
  createDebugBundleNavigationRef,
  onDebugBundleNavigationReady,
  onDebugBundleNavigationStateChange
} from "@debugbundle/sdk-react-native/navigation";

export const navigationRef = createDebugBundleNavigationRef();

export function AppNavigation() {
  return (
    <NavigationContainer
      ref={navigationRef}
      onReady={() => onDebugBundleNavigationReady(navigationRef)}
      onStateChange={() => onDebugBundleNavigationStateChange(navigationRef)}
    >
      {/* navigators */}
    </NavigationContainer>
  );
}

Expo

Expo development builds and prebuild are supported through the config plugin. Expo Go cannot load the native module, so the SDK reports degraded status and does not claim durable native queueing, native crash evidence, native device context, or remote-probe parity.

Verification

Run make verify for the TypeScript, package, and JavaScript coverage gates. Run make android-test for the Android bridge unit/coverage gate and make ios-test on macOS for the Swift and Objective-C++ bridge gates. make verify-native combines the JavaScript and available platform-native checks.

Release

The package publishes to npm from v* tags through GitHub Actions. Configure the repository secret NPM_TOKEN, make sure the tag matches package.json exactly, for example v1.2.0, and push the tag only after the exact Android and Swift native dependency line referenced by this package is available to Maven Central and CocoaPods consumers. The release workflow compiles clean apps against those published artifacts before npm publication.