Using our source map library you can upload source maps to unminify stack traces and get human-readable method names, files, and line numbers.
To configure your project to upload source maps and native mappings automatically, follow the showing full stacktraces guide for React Native.
The guide on this page shows how to upload source maps on-demand, which is useful when:
@bugsnag/source-maps
provides a CLI and a JavaScript library that can be used to upload your application’s source maps.
Install it globally on your system:
npm install --global @bugsnag/source-maps
# or
yarn global add @bugsnag/source-maps
Or locally inside your project:
npm install --save-dev @bugsnag/source-maps
# or
yarn add --dev @bugsnag/source-maps
The library can be used via the command line:
# CLI
bugsnag-source-maps upload-react-native <opts>
Or as a JavaScript API:
const { reactNative } = require('@bugsnag/source-maps')
interface reactNative {
async function uploadOne (UploadSingleOpts): Promise<void>
async function fetchAndUploadMultiple (FetchUploadOpts): Promise<void>
}
In addition to standard bundles, the Random Access Modules (RAM) bundle format is also supported. Delta bundles used in dev mode are not supported. They can be disabled via the in-app developer menu.
To upload React Native source maps in a development environment, you can use the @bugsnag/source-maps
CLI. This command will fetch the source map and bundle from the React Native bundle server (Metro).
bugsnag-source-maps upload-react-native \
--api-key YOUR_API_KEY_HERE \
--fetch \
--dev \
--platform ios \
--app-version YOUR_APP_VERSION
--app-bundle-version YOUR_APP_BUNDLE_VERSION \
bugsnag-source-maps upload-react-native \
--api-key YOUR_API_KEY_HERE \
--fetch \
--dev \
--platform android \
--app-version YOUR_APP_VERSION
--app-version-code YOUR_APP_VERSION_CODE \
If you’re running Metro somewhere other than the default (http://localhost:8081
), or your app’s entry point is not index.js
, you can provide these to the command using the --bundler-url
and --bundler-entry-point
arguments.
For release builds we recommend following the showing full stacktraces guide for React Native. The steps here are only required if you want to upload source maps on-demand.
If Hermes is enabled for Android, see the Hermes example.
If you’re using App Center CodePush, see the CodePush example.
The source maps used for the release variant can be generated via the react-native bundle
(or react-native ram-bundle
) command.
react-native bundle \
--dev false \
--entry-file index.js \
--platform ios \
--sourcemap-output ios-release.bundle.map \
--bundle-output ios-release.bundle
react-native bundle \
--dev false \
--entry-file index.js \
--platform android \
--sourcemap-output android-release.bundle.map \
--bundle-output android-release.bundle
The generated source map and bundle file can then be uploaded with the CLI:
bugsnag-source-maps upload-react-native \
--api-key YOUR_API_KEY_HERE \
--app-version YOUR_APP_VERSION \
--app-bundle-version YOUR_APP_BUNDLE_VERSION \
--platform ios \
--source-map ios-release.bundle.map \
--bundle ios-release.bundle
bugsnag-source-maps upload-react-native \
--api-key YOUR_API_KEY_HERE \
--app-version YOUR_APP_VERSION \
--app-version-code YOUR_APP_VERSION_CODE \
--platform android \
--source-map android-release.bundle.map \
--bundle android-release.bundle
If you’re using CodePush and Hermes together, refer to the CodePush and Hermes section instead.
If you are using Hermes on Android, you can use the standard instructions above for development builds.
For a release build, the bundle and source map are built as part of the Gradle build and are output in a different location.
First, build the app’s release variant:
cd android && ./gradlew assembleRelease
Then, use the CLI to upload the bundle and source map from their generated locations inside android/app/build/...
bugsnag-source-maps upload-react-native \
--api-key YOUR_API_KEY_HERE \
--app-version 1.2.3 \
--platform android \
--source-map android/app/build/generated/sourcemaps/react/release/index.android.bundle.map \
--bundle android/app/build/generated/assets/react/release/index.android.bundle
You must specify at least one (or both) of --app-version
or --app-version-code
.
If you’re using CodePush and Hermes together, refer to the CodePush and Hermes section instead.
When you release an update for your app using App Center CodePush, specify the --output-dir
in order to capture the source map and asset bundle files for upload.
appcenter codepush release-react \
--app <ownerName>/<appName> \
--output-dir build
Upload the source map, specifying the code bundle identifier instead of the app version/app version code.
bugsnag-source-maps upload-react-native \
--api-key YOUR_API_KEY_HERE \
--code-bundle-id 1.0.0-b12 \
--platform ios \
--source-map build/CodePush/main.jsbundle.map \
--bundle build/CodePush/main.jsbundle
bugsnag-source-maps upload-react-native \
--api-key YOUR_API_KEY_HERE \
--code-bundle-id 1.0.0-b12 \
--platform android \
--source-map build/CodePush/index.android.bundle.map \
--bundle build/CodePush/index.android.bundle
Release an update, ensuring that --output-dir
is set:
appcenter codepush release-react \
--app <ownerName>/<appName> \
--output-dir build
In the build/CodePush
directory, there will be two source maps that need to be merged. The React Native package provides a utility which will combine them into a single source map that can be uploaded to Bugsnag:
This extra step is required due to a limitation of the CodePush release-react
command. When this PR lands, the source maps will be combined automatically and this extra step will no longer be required.
./node_modules/react-native/scripts/compose-source-maps.js \
build/CodePush/index.android.bundle.map \
build/CodePush/index.android.bundle.hbc.map \
-o build/CodePush/index.android.bundle.composed.map
Finally, upload the combined source map:
bugsnag-source-maps upload-react-native \
--api-key YOUR_API_KEY_HERE \
--code-bundle-id 1.0.0-b12 \
--platform android \
--source-map build/CodePush/index.android.bundle.composed.map \
--bundle build/CodePush/index.android.bundle
The full set of options for @bugsnag/source-maps
.
Property (CLI, JS API) | Type | Description |
---|---|---|
--api-key , apiKey |
string |
your project’s API key [required] |
--app-version , appVersion |
string |
the version of the application you are building (this should match the appVersion configured in your notifier). |
--code-bundle-id , codeBundleId |
string |
for apps deployed with CodePush |
--app-version-code , appVersionCode |
string |
Android-only app version |
--app-bundle-version , appBundleVersion |
string |
iOS-only app version |
--dev , dev |
boolean |
indicates this is a debug build |
--endpoint , endpoint |
string |
customize the endpoint for Bugsnag On-Premise |
logger (JS only) |
Object |
provide a custom logger (must match the internal Logger interface) |
--no-overwrite , overwrite |
boolean |
whether to replace existing source maps uploaded with the same version (defaults to overwrite=true for React Native uploads – to set overwrite=false from the CLI use the --no-overwrite flag) |
--platform , platform |
string |
the application platform, either “android” or “ios” [required] |
--project-root , projectRoot |
string |
the top level directory of your project |
requestOpts (JS only) |
RequestOptions |
Supply options that should be passed to http.request() , for example if you need to provide an agent to send via a proxy. |
--quiet (CLI only) |
boolean |
less verbose logging |
Single upload options | ||
--source-map , sourceMap |
string |
the path to the source map [required] |
--bundle , bundle |
string |
the path to the bundle [required] |
Multiple upload options | ||
--fetch , fetch |
boolean |
enable fetch mode [required] |
--bundler-url , bundlerUrl |
string |
the URL of the React Native bundle server |
--bundler-entry-point , bundlerEntryPoint |
string |
the entry point of your React Native app |