React Native integration guide

Add Bugsnag to your React Native projects to automatically capture and report JavaScript and native crashes in your Android and iOS apps.


Add the bugsnag-react-native package to your dependencies in package.json:

npm install bugsnag-react-native --save

If you are using a version of react-native that is older than 0.40.0 then you must install the older 1.2 version of bugsnag-react-native

npm install bugsnag-react-native@^1.3 --save

Native component installation

Run react-native link to install and configure the included native components of the library.

Showing full stacktraces

Follow the showing full stacktraces guide to get source maps, ProGuard mapping, and debug symbol maps (dSYMS) integrated into your error reports.

Basic configuration

Android native configuration

Set your API key in your AndroidManifest.xml.

<application ...>
  <meta-data android:name=""

Then, initialize Bugsnag in the onCreate function of

import com.bugsnag.BugsnagReactNative;
import android.os.Bundle;
// MainActivity class
  public void onCreate(Bundle savedInstanceState) {

iOS native configuration

Set your API key in your Info.plist file.


Then, initialize Bugsnag in the application:didFinishLoadingWithOptions: method of your AppDelegate.

#import <BugsnagReactNative/BugsnagReactNative.h>
// ...
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
    [BugsnagReactNative start];
    // ...

JavaScript configuration

Initialize the Bugsnag client from your bundle index files:

import { Client } from 'bugsnag-react-native';

const bugsnag = new Client();

Further configuration

If you’d like to configure Bugsnag further, check out the configuration options reference.

Reporting unhandled errors

After completing installation and basic configuration, unhandled JavaScript errors and native crashes will be reported and automatically appear on your Bugsnag dashboard.

Reporting handled errors

If you would like to send handled errors to Bugsnag, you can pass any Error object to Bugsnag’s notify method:

try {
  // potentially crashy code
} catch (error) {

Adding diagnostics or adjusting severity

It can often be helpful to adjust the severity or attach custom diagnostics to handled errors. For more information, see reporting handled errors.

Reporting handled native exceptions

The Bugsnag React Native library depends on the Bugsnag Cocoa or Android libraries, which have notify functions for reporting handled exceptions from native code. See the reporting handled exceptions guides for iOS or Android for more information.

Reporting promise rejections

By default, unhandled promise rejections are reported in production. To report an individual rejection, use notify() as a part of the catch block:

new Promise(function(resolve, reject) {
  /* potentially failing code */
.then(function () { /* if the promise is resolved */ })
.catch(this.client.notify); // if the promise is rejected

For more information, see the handlePromiseRejections configuration option reference.

Sending diagnostic data

Automatically captured diagnostics

Bugsnag will automatically capture and attach the following diagnostic data:

  • A full stacktrace
  • Battery state
  • Device model and OS version
  • Thread state for all threads
  • Release stage (production, debug, etc)
  • App running duration in the foreground and/or background
  • A device- and vendor-specific identifier

Attaching custom diagnostics

It can often be helpful to attach application-specific diagnostic data to exception reports. This can be accomplished by adding a report callback to notify. The callback is invoked before the report is sent to Bugsnag:

this.client.notify(error, function(report) {
  report.metadata = { "account": {
    "company": "Acme Co",
    "id": 123

It is also possible to inspect and modify exception reports before they are delivered using beforeSendCallbacks. See the beforeSendCallbacks reference for more details.

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. Information set on the Bugsnag client is sent with each error report:

this.client.setUser('1234', 'Jessica Jones', '');

For more information, see configuration options.

Identifying users in native code

The Bugsnag React Native library depends on the Bugsnag Cocoa or Android libraries, which have setUser functions for identifying users from native code. See the identifying users guides for iOS or Android for more information.

Logging breadcrumbs

In order to understand what happened in your application before each crash, it can be helpful to leave short log statements that we call breadcrumbs. The last several breadcrumbs are attached to a crash to help diagnose what events lead to the error.

Automatically captured breadcrumbs

By default, Bugsnag captures common events including:

  • Low memory warnings
  • Device rotation (if applicable)
  • Menu presentation
  • Screenshots
  • Undo and redo
  • Table view selection
  • Window visibility changes
  • Non-fatal errors

Attaching custom breadcrumbs

To attach additional breadcrumbs, use the leaveBreadcrumb function:

this.client.leaveBreadcrumb('load main view', {type: 'navigation'});

When logging breadcrumbs, we’ll keep track of the timestamp, and show both the message and timestamp on your dashboard.

For more information or to customize the diagnostics sent with a breadcrumb, see Adding detailed breadcrumbs.

Logging breadcrumbs in native code

The Bugsnag React Native library depends on the Bugsnag Cocoa or Android libraries, which have leaveBreadcrumb functions for logging breadcrumbs from native code. See the identifying users guides for iOS or Android for more information.

Next steps