@debugbundle/sdk-react-native

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

Release candidate 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.
• Clean-install React Native app smoke coverage for Android and iOS, including New Architecture codegen/autolinking.

Before public npm publication, publish or otherwise make the native DebugBundle iOS pod available to CocoaPods consumers. Local smoke tests inject the sibling Swift SDK pod path so the bridge can be validated before registry publication.

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. Until that pod is published to the public CocoaPods specs repo, local validation must add the Swift SDK pod path to the app Podfile.

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.

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 v0.1.0, and push the tag after the native Swift DebugBundle pod is available to CocoaPods consumers.