Legacy React Native integration guide

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

This documentation is for the original BugSnag React Native SDK. We recommend upgrading to the React Native package that is now part of the Universal JavaScript SDK using our Upgrade guide. Documentation for the latest release can be found here.


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

npm install bugsnag-react-native --save

React Native 0.60+

For projects using iOS, open the ios/ subdirectory of the project and run pod install:

cd ios/ && pod install

Android components are configured automatically.

React Native <0.60

If you are running a version of React Native before 0.60, configure the library’s native components:

react-native link bugsnag-react-native

Basic configuration

To identify your app in the BugSnag dashboard, you’ll need to configure your BugSnag API key.

Import and initialize BugSnag within your app’s entry point, typically index.js (or index.ios.js and index.android.js):

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

You can find your API key in Project Settings from your BugSnag dashboard.

At this point, BugSnag should be installed and configured, and any unhandled errors and native exceptions will be automatically detected and should appear in your BugSnag dashboard.

Enhanced native integration

If your app has native components which run before React Native is initialized, or C/C++ components on Android, complete the steps in the Enhanced native integration guide to track those crashes.

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 Android and iOS 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', 'jess@example.com');

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 breadcrumb guides for iOS or Android for more information.

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 autoCaptureSessions configuration option.

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

  • The app is launched
  • The app enters the foreground for the first time in 60 seconds

If you want control over what is deemed a session, you can switch off automatic session tracking with the autoCaptureSessions option, and manage the session lifecycle using startSession(), stopSession() and resumeSession().

Next steps