React Native

Introduction 👋

BugSplat's @bugsplat/expo package provides crash and error reporting for React Native (Expo) apps across iOS, Android, and Web. BugSplat collects native crash reports, JavaScript errors, and custom metadata so that you can fix bugs and deliver a better user experience. Visit bugsplat.com for more information and to sign up for an account.

Platform	Native Crashes	JS Error Reporting
iOS	bugsplat-apple (PLCrashReporter)	HTTP POST to /post/js/
Android	bugsplat-android (Crashpad)	HTTP POST to /post/js/
Web	N/A	bugsplat-js

Requirements 📋

• The bugsplat-android SDK requires Android minSdk 26 (Android 8.0+).

• An Expo managed or bare workflow project.

Installation 🏗️

Install the @bugsplat/expo package:

npx expo install @bugsplat/expo

Configuration ⚙️

Add the BugSplat config plugin to your app.json or app.config.js. Credentials for symbol upload can be set via environment variables (BUGSPLAT_CLIENT_ID, BUGSPLAT_CLIENT_SECRET) or directly in the plugin config.

{
  "expo": {
    "plugins": [
      ["@bugsplat/expo", {
        "database": "your-database",
        "enableSymbolUpload": true
      }],
      ["expo-build-properties", {
        "android": {
          "minSdkVersion": 26
        }
      }]
    ]
  }
}

If your project's minSdkVersion is already >= 26, the expo-build-properties plugin is not needed.

Plugin Options

Option	Required	Description
database	No	BugSplat database name (can also be set via init() or BUGSPLAT_DATABASE env var)
enableSymbolUpload	No	Enable automatic symbol upload for iOS (dSYMs) and Android (.so files)
symbolUploadClientId	No	BugSplat API client ID (or set BUGSPLAT_CLIENT_ID env var)
symbolUploadClientSecret	No	BugSplat API client secret (or set BUGSPLAT_CLIENT_SECRET env var)

Usage 🧑‍💻

Initialization

Call init() before using any other BugSplat functions. Replace your-database, YourApp, and 1.0.0 with your BugSplat database name, application name, and version.

import { init } from '@bugsplat/expo';

await init('your-database', 'YourApp', '1.0.0', {
  userName: '[email protected]',
  userEmail: '[email protected]',
  appKey: 'optional-key',
});

Options:

• appKey?: string — Queryable metadata key

• userName?: string — User name for reports

• userEmail?: string — User email for reports

• autoSubmitCrashReport?: boolean — Auto-submit crashes (iOS only, default: true)

• attributes?: Record<string, string> — Custom key-value attributes

• attachments?: string[] — File paths to attach (native only)

• description?: string — Default description

Reporting Errors

Manually report caught errors using post():

import { post } from '@bugsplat/expo';

try {
  riskyOperation();
} catch (error) {
  const result = await post(error);
  console.log(result.success ? 'Reported!' : result.error);
}

Error Boundary

Wrap your component tree in <ErrorBoundary> to catch React render errors and report them to BugSplat automatically. This works on all platforms — iOS, Android, and Web.

import { ErrorBoundary } from '@bugsplat/expo';

function App() {
  return (
    <ErrorBoundary fallback={<Text>Something went wrong</Text>}>
      <MyComponent />
    </ErrorBoundary>
  );
}

The fallback prop accepts a React node or a render function:

<ErrorBoundary
  fallback={({ error, resetErrorBoundary }) => (
    <View>
      <Text>{error.message}</Text>
      <Button title="Try again" onPress={resetErrorBoundary} />
    </View>
  )}
>
  <MyComponent />
</ErrorBoundary>

User Info

Update user info for subsequent reports:

import { setUser } from '@bugsplat/expo';

setUser('Jane Doe', '[email protected]');

Attributes

Set custom key-value attributes that are searchable in the BugSplat dashboard:

import { setAttribute } from '@bugsplat/expo';

setAttribute('environment', 'production');

Custom attributes via setAttribute are not supported on web.

Symbol Upload 📦

Production crash reports require debug symbols to produce readable stack traces. When enableSymbolUpload is set in your plugin config, symbols are uploaded automatically during iOS and Android release builds.

For manual uploads or CI/CD workflows, use @bugsplat/symbol-upload:

npm install --save-dev @bugsplat/symbol-upload

iOS dSYMs:

npx @bugsplat/symbol-upload \
  -b your-database -a YourApp -v 1.0.0 \
  -i $BUGSPLAT_CLIENT_ID -s $BUGSPLAT_CLIENT_SECRET \
  -d /path/to/build/Products/Release-iphoneos \
  -f "**/*.dSYM"

Android .so files:

npx @bugsplat/symbol-upload \
  -b your-database -a YourApp -v 1.0.0 \
  -i $BUGSPLAT_CLIENT_ID -s $BUGSPLAT_CLIENT_SECRET \
  -d android/app/build/intermediates/merged_native_libs \
  -f "**/*.so" -m

JavaScript source maps (after npx expo export --source-maps):

npx @bugsplat/symbol-upload \
  -b your-database -a YourApp -v 1.0.0 \
  -i $BUGSPLAT_CLIENT_ID -s $BUGSPLAT_CLIENT_SECRET \
  -d dist \
  -f "**/*.map"

Run npx @bugsplat/symbol-upload --help for all options.

Testing Native Crashes 🧪

To test native crash reporting, you must run a release build — the debugger intercepts crashes in debug builds.

# iOS
npx expo run:ios --configuration Release

# Android
npx expo run:android --variant release

Trigger a test crash to verify your integration:

import { crash } from '@bugsplat/expo';

// Triggers a native crash (iOS/Android) or throws an error (web)
crash();

iOS: Crash reports are captured at crash time and uploaded on the next app launch when init() is called again. After triggering a test crash, relaunch the app to upload the pending report.

Android: Crash reports are captured and uploaded immediately at crash time by the Crashpad handler process.

Troubleshooting 🔧

Android: Crashes not uploading on emulator

The Crashpad handler process requires native libraries to be extracted to disk. The @bugsplat/expo config plugin sets extractNativeLibs=true automatically. If you're still not seeing crashes:

• Use a google_apis emulator image (not google_apis_playstore). The Play Store emulator images have restrictions that prevent Crashpad's handler process from executing.

• Alternatively, test on a physical Android device where this is not an issue.

iOS: No crash report after test crash

Make sure you relaunch the app and call init() again after the crash. PLCrashReporter saves the crash to disk and uploads it on the next launch.

Not finding what you're looking for? Please reach out to [email protected] for further assistance.