Your React Native app can send stacktraces to BugSnag in both JavaScript format as well that of the native Android or Apple device. If the code in your app is obfuscated or minified then you will need to upload various files to BugSnag so that a full stacktrace with methods, file paths and line numbers can be shown.
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.
BugSnag provides various tools to simplify this process. If you used our React Native CLI package (npx @bugsnag/react-native-cli init) to install and configure BugSnag then this will have installed hooks into your build system where this can be automated.
This page provides the options available for each file upload type so that you can choose which is most suited to your needs.
The file types to consider for upload are:
We are in the process of converting our tooling to use the universal BugSnag CLI or its NPM wrapper @bugsnag/cli. In the longer-term this will greatly simplify uploading all the files required for React Native. However at present what is required for each file type differs a little.
The bundle files and source maps generated by both the Android and Apple builds need to be uploaded in order to see unminified source code for JavaScript errors.
If you’re using CodePush, you’ll need to upload maps manually with the @bugsnag/source-maps tool. See our examples for CodePush.
Follow either the Automatic or Manual instructions below to start uploading these files. However please be aware that there is a difference between how the upload is triggered for Android and Apple 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.
The automatic setup in the BugSnag React Native CLI (and equivalent manual instructions) previously used the BugSnag Android Gradle plugin to upload JavaScript source maps for Android during a build. However, the BugSnag CLI is now used to upload source maps for Android as a separate step after they have been generated by the React Native build.
If you are following this guide and set your BugSnag integration up prior to September 2023, please ensure the uploadReactNativeMappings option is removed/disabled in your android/build.gradle file to prevent the Gradle build attempting the upload.
If you ran the BugSnag React Native CLI to integrate BugSnag, this will have installed the additional NPM packages to perform the uploads.
If you didn’t run init, or you answered “no” to the uploading mappings prompt, you can use the automate-symbolication command separately to add these settings.
Once your app is built, run the following after each build to upload source maps:
npm run bugsnag:upload-android && bugsnag:upload-ios
This task calls the BugSnag CLI to perform an upload with information in your project files. If your build contains multiple Android build variants or has a non-standard project layout, you might need to provide extra options. See the react-native-android or react-native-ios command reference for more information.
On Android, source maps are automatically generated during the Gradle build.
To enable generation of source maps for iOS, set the SOURCEMAP_FILE environment variable during the Xcode build. To do this for all builds, we recommend adding this to your .env file:
SOURCEMAP_FILE=build_outputs/sourcemaps/todo
@bugsnag/cliYour source maps can then be uploaded using the BugSnag CLI, which can either be installed manually or via an NPM package:
npm install --save-dev @bugsnag/cli
# or
yarn add --dev @bugsnag/cli
Once installed, we suggest adding a new task to your package.json to call the react-native-android and react-native-ios commands:
"bugsnag:upload-android": "./node_modules/.bin/bugsnag-cli upload react-native-android"
"bugsnag:upload-ios": "./node_modules/.bin/bugsnag-cli upload react-native-ios"
Once your app is built, run the following after each build to upload source maps:
npm run bugsnag:upload-android && bugsnag:upload-ios
This calls the BugSnag CLI to perform an upload with information in your project files. If your build contains multiple Android build variants or has a non-standard project layout, you might need to provide extra options. See the react-native-android or react-native-ios command reference for more information.
You can integrate source map uploads directly into your native builds by calling the BugSnag CLI react-native-android and react-native-ios commands using a Gradle task or Xcode post-build phase – or equivalent for your build system – passing in the path to the project.
If you are using minification tools, such as ProGuard, DexGuard, or R8 to minify and optimize your Android app, this will cause method and class names to become obfuscated which makes debugging harder. Similarly, for applications which use the NDK, native stacktraces from C or C++ code consist of a list of addresses and numeric offsets.
If you ran the BugSnag React Native CLI to integrate BugSnag, the BugSnag Android Gradle plugin will have been installed in your app’s build.gradle file.
If you didn’t run init, or you answered “no” to the uploading mappings prompt, you can use the automate-symbolication command separately to add these settings.
By installing the BugSnag Gradle Plugin, NDK and ProGuard mapping files can be uploaded during a Gradle build of the native app.
Alternatively you can use the BugSnag CLI to upload the NDK and ProGuard mapping files after the Gradle build has completed. This can be useful for fine-grained control over uploads and in CI environments.
For more details on these options, please see our native Android stacktrace guide.
Stacktraces from Apple platforms include backtraces with memory addresses, but symbolication is required to replace the memory addresses with human-readable function names, file paths, and line numbers. BugSnag supports symbolicating crash reports using the contents of your debug symbol (dSYM) files, which are generated when compiling your app.
The BugSnag React Native CLI does not currently perform any setup related to dSYM files.
To upload dSYM files as part of a Xcode build, you can install the cocoapods-bugsnag RubyGem to add the upload into your Xcode project’s build phase. Alternatively you can use the bugsnag-dsym-upload tool after a build to upload the dSYMs or use our Fastlane plugin if you deploy through Fastlane.
For more details on these options, please see our native iOS stacktrace guide.