githubEdit

React Native

Introduction 👋

BugSplat's @bugsplat/expoarrow-up-right 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.comarrow-up-right for more information and to sign up for an account.

Platform
Native Crashes
JS Error Reporting

iOS

HTTP POST to /post/js/

Android

HTTP POST to /post/js/

Requirements 📋

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

  • An Expoarrow-up-right 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
        }
      }]
    ]
  }
}
circle-info

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.

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():

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.

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

User Info

Update user info for subsequent reports:

Attributes

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

circle-info

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-uploadarrow-up-right:

iOS dSYMs:

Android .so files:

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

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.

Trigger a test crash to verify your integration:

circle-info

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.

circle-info

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

Last updated

Was this helpful?