React Native integration guide

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

New to Bugsnag? Create an account now.


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

yarn add 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.3 version of bugsnag-react-native:

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

If you use Code Push, lock the library to the latest patch version:

"dependencies": {
    "bugsnag-react-native": "~2.9.3"

Configure the library’s native components:

react-native link bugsnag-react-native

Note: if you are using CocoaPods to manage dependencies in your React Native application, run pod install after react-native link

Import and initialize Bugsnag within your app’s entry point, typically index.js (or index.ios.js and

import { Client } from 'bugsnag-react-native';
const bugsnag = new Client();

Basic configuration

Android native installation

Specify Google’s maven repository in android/build.gradle:

allprojects {
    repositories {
        maven { url '' }

Set your API key in your AndroidManifest.xml. You can find your API key on the Project Settings page on your Bugsnag dashboard:

<meta-data android:name=""

Initialize Bugsnag in the onCreate function of Add the class if it does not yet exist.

// MainApplication class
public void onCreate() {
    SoLoader.init(this, /* native exopackage */ false);

iOS native installation

Set your API key in Info.plist. You can find your API key on the Project Settings page on your Bugsnag dashboard:


Initialize Bugsnag in the application:didFinishLaunchingWithOptions: method of your AppDelegate.

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

TypeScript support

TypeScript definitions are provided. Simply import { Client } from 'bugsnag-react-native' in your .ts files.

Further configuration

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

Showing full stacktraces

Follow the showing full stacktraces guide to set up source maps, ProGuard mapping, and debug symbol maps (dSYMs) so you can see the original method names, file paths, and line numbers in stack traces.

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.

Running in development mode

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. Bugsnag will always automatically capture unhandled errors from your production apps.

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(bugsnag.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:

bugsnag.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:

bugsnag.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.

Disabling error reporting

If you wish to disable error reporting, you can return false within a registered callback. This would allow for users to opt out of sending error reports, for example:

configuration.registerBeforeSendCallback(function(report, error) {
    return false; // no error report will be sent

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
  • Screenshot capture (not the screenshot itself)
  • Undo and redo
  • Table view selection
  • Window visibility changes
  • Non-fatal errors
  • Log messages (off by default, see configuration options)

Attaching custom breadcrumbs

To attach additional breadcrumbs, use the leaveBreadcrumb function:

bugsnag.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.

Session tracking

Bugsnag can track the number of “sessions” that happen in your application. This enables Bugsnag to provide and compare crash rates between releases to help you understand the quality of your releases. This functionality is disabled by default, but can be enabled through the configuration:

import { Client, Configuration } from "bugsnag-react-native";

const configuration = new Configuration();
configuration.autoCaptureSessions = true;

const bugsnag = new Client(configuration);

Using this option, Bugsnag will report a session each time:

  • The app is launched
  • The app enters the foreground

To control what is considered a session, rather than using the autoCaptureSessions option, call bugsnag.startSession() when appropriate for your application.

For more information on available configuration options, see the Configuration options reference.

Next steps