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
For projects using iOS, open the ios/ subdirectory of the project and run pod install:
cd ios/ && pod install
Android components are configured automatically.
If you are running a version of React Native before 0.60, configure the library’s native components:
react-native link bugsnag-react-native
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.
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 definitions are provided. Simply import { Client } from 'bugsnag-react-native' in your .ts files.
If you’d like to configure BugSnag further, check out the configuration options reference.
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.
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.
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.
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) {
bugsnag.notify(error);
}
It can often be helpful to adjust the severity or attach custom diagnostics to handled errors. For more information, see reporting handled errors.
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.
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.
BugSnag will automatically capture and attach the following diagnostic data:
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.
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.
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.
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
});
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.
By default, BugSnag captures common events including:
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.
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.
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:
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().
bugsnag-react-native, the library
powering BugSnag for React Native, on GitHub