React Native integration guide

Add BugSnag to your React Native apps to report JavaScript and native errors.

New to BugSnag? Create an account

Looking for performance monitoring? See our performance guide

Note for Expo users

If you’re using Expo, unless you have ejected your app or are using the bare workflow, see the Expo guide. Otherwise, continue with the React Native guide below to integrate BugSnag on supported platforms.

Installation and configuration

The easiest way to add BugSnag to your React Native project is to use our CLI (macOS and Linux only):

# using npx (recommended)
npx @bugsnag/react-native-cli init
# using npm or yarn (if npx isn't available)
npm install --global @bugsnag/react-native-cli
# or
yarn global add @bugsnag/react-native-cli

# then
bugsnag-react-native-cli init

The CLI will walk you through:

  • Installing BugSnag package dependencies
  • Adding your API key to the native configuration files
  • Initializing BugSnag in the JS, Android and iOS parts of your app
  • Updating your build process to send mapping files to BugSnag for symbolicated stack traces – the showing full stacktraces guide for full details

Alternatively you can follow the manual setup guide for instructions on integrating BugSnag manually.

These docs are for the @bugsnag/react-native package, which supports React Native v0.60 and above.

If you’re using the previous bugsnag-react-native package, we recommend upgrading to the latest release, unless you’re using a version of React Native older than 0.60. Documentation for bugsnag-react-native can be found on our legacy pages.

Capturing React render errors

The BugSnag ErrorBoundary allows you to capture React render errors in your application. You can also use the FallbackComponent to display a custom error screen to your users:

// Start BugSnag first...

// Create the error boundary...
const ErrorBoundary = Bugsnag.getPlugin('react').createErrorBoundary(React)

const ErrorView = () =>
    <Text>Inform users of an error in the component tree.</Text>

const App = () => {
  // Your main App component

export default () =>
  <ErrorBoundary FallbackComponent={ErrorView}>
    <App />

See our guide on capturing render errors to learn more about the ErrorBoundary and FallbackComponent.

If you use either React Navigation or React Native Navigation packages in your app, you can automatically capture your users’ navigation history.

See Navigation libraries for integration instructions.

TypeScript support

Type definitions are provided and will be picked up automatically by the TypeScript compiler when you import @bugsnag/react-native.

Monorepo support

If you’re using @bugsnag/react-native in a monorepo, you’ll need to configure the nodeModulesDir option in your build.gradle of the Android app to tell BugSnag where your node_modules directory is. No further configuration is required for your iOS project.

Further configuration

Most of BugSnag’s behavior in a React Native app is configured through the native BugSnag libraries that are linked to your Android and iOS projects. This ensures that your desired behavior is present from startup and does not change when the JavaScript runtime starts.

Check out the configuration options reference for a list of available options.

Showing full stacktraces

Uploading source maps, Android mappings, and iOS debug symbol maps (dSYMs) enables you to see the original method names, file paths, and line numbers in stacktraces.

If you used npx @bugsnag/react-native-cli init to install and configure BugSnag, it will have configured your project so that these mapping files can be uploaded when your app is built. However further manual integration is necessary to ensure that all the required files are uploaded.

See the showing full stacktraces guide for detailed instructions on how to integrate BugSnag into your builds.

React Native 0.71 made significant changes to the Android build system and our upload tooling and instructions have had to change alongside it. If you are upgrading React Native version to 0.71+ or configured your BugSnag integration prior to September 2023, please re-read the showing full stacktraces guide to ensure you have covered each of the file types for upload.

Reporting unhandled errors

After completing installation and configuration, unhandled errors and promise rejections in JavaScript, as well as native Android and iOS crashes will be reported automatically and appear on your BugSnag dashboard.

React Native’s In-app Error screen can interfere with the automatic capture of unhandled native crashes. If you want to send these unhandled errors to BugSnag in the course of development, we recommend running your app in release mode.

Reporting out-of-memory terminations

On iOS platforms, BugSnag automatically detects terminations of your app caused by the operating system due to high memory usage.

OOM detection is enabled by default as part of the basic configuration steps. If you wish to disable it, see the enabledErrorTypes configuration option.

OOMs are sent to your BugSnag dashboard when the app next launches. OOMs will not be reported when the debugger is attached.

Reporting ANRs and fatal app hangs

When your app fails to respond to interactions in real time it causes user frustration and can lead them to abandon your app altogether.


When the main thread of an Android app is blocked for too long, it appears unresponsive and the Android OS creates an Application Not Responding (ANR) error, presenting the user with a dialog option to force quit the app.

ANR detection is enabled by default as part of the installation and configuration steps. If you wish to disable it, see the enabledErrorTypes Android configuration option.


When the main thread of an app is unresponsive for a period of time it will appear to have frozen and may be terminated by the system watchdog as described in Apple’s documentation.

Detection of these “fatal” app hangs is enabled by default as part of the basic configuration steps. If you wish to disable it, see the enabledErrorTypes configuration option. By default fatal app hangs are reported when the app is terminated after the main thread has been unresponsive for 2000ms.

You can also report non-fatal app hangs (i.e. hangs that did not result in the app being killed) by configuring a minimum app hang threshold duration. This threshold applies to both fatal and non-fatal app hangs and is used by BugSnag to prepare an app hang event report when it is exceeded; if the app subsequently recovers from the hang, a non-fatal hang is reported otherwise a fatal hang will be reported if the app is terminated.

Fatal app hangs are sent to your BugSnag dashboard when the app next launches.

See the Reporting app hangs guide for more information.

Reporting thermal kills

On iOS platforms, BugSnag detects terminations of your app by the operating system due to the device overheating.

Thermal kill detection is enabled by default as part of the basic configuration steps. If you wish to disable it, see the enabledErrorTypes configuration option.

Thermal kill events are sent to your BugSnag dashboard when the app next launches. They will not be reported when the debugger is attached.

Reporting handled errors

Sometimes it is useful to manually notify BugSnag of a problem. To do this, call Bugsnag.notify(). For example:

try {
} catch (e) {

When reporting handled errors, it’s often helpful to send custom diagnostic data or to adjust the severity of particular errors. You can also report native errors from your iOS and Android projects.

For more information, see reporting handled errors.

Sending diagnostic data

Automatically captured diagnostics

BugSnag will automatically capture and attach the following diagnostic data:

  • Full stack traces for all threads.
  • App state including running time and time in foreground.
  • Build information including name, version/build and release stage.
  • Device specification including model, OS version and total memory.
  • System state including orientation, free memory, available disk space and battery level.

For more information see Automatically captured data.

Attaching custom diagnostics

It can often be helpful to attach application-specific diagnostic data to error reports. This can be accomplished by setting a callback which will be invoked before any reports are sent to BugSnag.

The following adds a map of data to the “company” tab on the BugSnag dashboard for all captured events:

  onError: function (event) {
    event.addMetadata('company', {
      name: "Acme Co.",
      country: "uk"

You can also attach metadata that comes from native code in your iOS and Android projects using the addMetadata functions on the native BugSnag client.

For more information, see Customizing error reports.

Identifying users

In order to correlate errors with customer reports, or to see a list of users who experienced each error, it is helpful to capture and display user information on your BugSnag dashboard.

You can set the user information of an error report using the user configuration property when BugSnag starts or via an onError callback.

  onError: function (event) {
    event.setUser('3', '', 'Bugs Nag')

If your user data is located in native code, you can also set this information using the setUser function on the native BugSnag client.

For more information, see Adding user data.

Logging breadcrumbs

In order to understand what happened in your application before each error, it can be helpful to leave short log statements that we call breadcrumbs. A configurable number of breadcrumbs are attached to each error report to help diagnose what events led to the error.

Automatically captured breadcrumbs

By default, BugSnag captures common events including:

  • Low memory warnings
  • Device rotation
  • Menu presentation
  • Screenshot capture (not the screenshot itself)
  • Undo and redo
  • Table view selection
  • Window visibility changes
  • Non-fatal errors
  • Log messages
  • User navigation (when enabled through our navigation plugins)
  • HTTP requests (from JavaScript layer)

Attaching custom breadcrumbs

You can use the leaveBreadcrumb method to log potentially useful events in your own applications:

Bugsnag.leaveBreadcrumb('Button clicked')

BugSnag will keep track of the time and order of the breadcrumbs and show them on your dashboard. Additional data can also be attached to breadcrumbs by providing the optional metadata parameter.

You can leave breadcrumbs in your iOS and Android projects too using the leaveBreadcrumb function on the native BugSnag client.

For more information and examples for how custom breadcrumbs can be integrated, see Customizing breadcrumbs.

Session tracking

BugSnag tracks the number of “sessions” that happen within your application. This allows you to compare stability scores between releases and helps you to understand the quality of your releases.

Sessions are captured and reported by default. This behavior can be disabled using the autoTrackSessions configuration option.

BugSnag will automatically report a session each time the app is launched or enters the foreground for the first time in 30 seconds.

For more information about controlling session tracking, see Capturing sessions.

Declaring feature flags and experiments

Monitor errors as you roll out features or run experiments and A/B tests by declaring your feature flag and experiment usage in the BugSnag client. You can use the Features dashboard to identify whether these features have introduced errors into your app.

Bugsnag.addFeatureFlag('Checkout button color', 'Blue')
Bugsnag.addFeatureFlag('New checkout flow')

For more information, see Feature flags & experiments.

Identifying crashes at launch

By default BugSnag will identify crashes that occur whilst your app is launching, allowing you to prioritize fixing high-impact launch crashes.

Additionally you can use BugSnag to detect recurrent launch crashes: allowing you to take evasive action in your app, such as resetting data or turning off application features.

Follow the Identifying crashes at launch guide for Android and iOS to configure this functionality.

Next steps