Hermes
Sentry added support for react-native
builds that use the hermes
engine, which required changes to the Sentry SDK, sentry-cli
as well as Sentry itself.
Sentry customers using the
sentry-cli
.
The minimum required version for the SDK is @sentry/react-native
SDK version 1.3.3
,
and @sentry/cli
version 1.51.1
.For self-hosted Sentry users, the minimum version required is f07352b.
Once you have the minimum version of the SDK, Sentry provides the standard integration as described in the React Native Sentry documentation.
If you are using Hermes, you should not have the RAM bundles feature enabled. In Hermes, when loading the bytecode, mmap
ensures that the entire file is not loaded. Using Hermes with RAM bundles might lead to issues, because those mechanisms are not compatible with each other.
Source Maps
If you do not need custom source maps, the sentry.gradle
build step fully supports Hermes source maps.
Custom Source Maps
This document walks through the steps to manually generate and upload custom source maps. When generating your source maps, it's important to match the steps of your React Native tooling exactly, otherwise the generated bundle won't work correctly, and your errors may point to unrelated lines.
The React Native tooling steps are extracted from react-native-xcode.sh
for iOS and from BundleHermesCTask.kt
for Android.
BundleHermesCTask.kt
is only available from version 0.71
on. For previous versions, use react.gradle
.
Compile Source maps
Depending on how your app bundle was generated not all these compilation steps are required:
- If you use
EXTRA_PACKAGER_ARGS
oniOS
, only the first step applies. This is the default behavior if you used@sentry/wizard
. - If you use
SOURCEMAP_FILE
, all steps are necessary.
We recommend using the bundle and source maps generated by React Native tooling. If you are having issues with the manually generated artifacts see this issue for more information.
- Bundle/minify with
metro
(react-native
) to get the bundle (.bundle
or.jsbundle
) and packager source map (.map
):
React Native 0.70
and CodePush Update minifies the packager bundle by default.
npx react-native bundle --platform android --dev false --entry-file index.js --reset-cache --bundle-output index.android.bundle --sourcemap-output index.android.bundle.packager.map --minify false
- Compile to bytecode using
hermes
to get the compiler source map (.hbc.map
):
OS-BIN
is osx-bin
, win64-bin
, or linux64-bin
, depending on which operating system you are using.
If you're using Hermes with React Native 0.68 or below:
node_modules/hermes-engine/{OS-BIN}/hermesc -O -emit-binary -output-source-map -out=index.android.bundle.hbc index.android.bundle
rm -f index.android.bundle
mv index.android.bundle.hbc index.android.bundle
Starting with React Native 0.69, hermes
has been shipped with React Native, so you should use hermesc
from react-native
:
node_modules/react-native/sdks/hermesc/{OS-BIN}/hermesc -O -emit-binary -output-source-map -out=index.android.bundle.hbc index.android.bundle
rm -f index.android.bundle
mv index.android.bundle.hbc index.android.bundle
- Merge the two source maps using
compose-source-maps
to get the final source map (.map
):
node node_modules/react-native/scripts/compose-source-maps.js index.android.bundle.packager.map index.android.bundle.hbc.map -o index.android.bundle.map
Upload the Bundle and Source Maps
Upload your source maps following Step 3 on the normal source maps guide.
You will upload the index.android.bundle
and index.android.bundle.map
for Android, main.jsbundle
and main.jsbundle.map
for iOS.
When uploaded, the index.android.bundle
file will be sized at 0 bytes. This is expected with Hermes bytecode and won't affect the source maps resolution.
Upload Using Sentry Fastlane Plugin
To upload generated sourcemaps using Fastlane, use the sentry_upload_sourcemap
action. See how to install Sentry Fastlane Plugin here.
sentry_upload_sourcemap(
auth_token: 'sntrys_YOUR_TOKEN_HERE',
org_slug: 'example-org',
project_slug: 'example-project',
version: '...',
app_identifier: '...', # bundle_identifer of your app
build: '...', # optional build number of your app
dist: '...', # optional distribution of the release usually the buildnumber
sourcemap: ['index.android.bundle', 'index.android.bundle.map'],
rewrite: true
)
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) to suggesting an update ("yeah, this would be better").
- Package:
- npm:@sentry/react-native
- Version:
- 5.10.0
- Repository:
- https://github.com/getsentry/sentry-react-native