Hermes

Sentry's React Native SDK works out of the box with applications using Hermes engine. To see readable stack traces in the product source maps need to be uploaded to Sentry. This guide explains how to manually upload source maps from Hermes engine.

Set Up Automatic Upload

The easiest way to configure automatic source maps upload is to use the Sentry Wizard:

npx @sentry/wizard@latest -i reactNative

Manual Upload

To manually upload source maps, first, you need to generate the source maps and bundle. Then compile the Hermes bytecode bundle, and finally upload the source map to Sentry.

Start with adding Sentry React Native Metro Plugin to your metro.config.js:

const { getDefaultConfig } = require("@react-native/metro-config");
const { withSentryConfig } = require("@sentry/react-native/metro");

const config = getDefaultConfig(__dirname);
module.exports = withSentryConfig(config);

Generate the React Native Packager (Metro) bundle and source maps:

npx react-native bundle \
  --dev false \
  --minify false \
  --platform android \
  --entry-file index.js \
  --reset-cache \
  --bundle-output index.android.bundle \
  --sourcemap-output index.android.bundle.map

Compile Hermes bytecode bundle and source map:

node_modules/react-native/sdks/hermesc/osx-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

Compose Hermes bytecode and (React Native Packager) Metro source maps:

mv index.android.bundle.map index.android.bundle.packager.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
node \
  node_modules/@sentry/react-native/scripts/copy-debugid.js \
  index.android.bundle.packager.map index.android.bundle.map
rm -f index.android.bundle.packager.map

Make sure sentry-cli is configured for your project and set up your environment variables:

SENTRY_ORG=example-org
SENTRY_PROJECT=example-project
SENTRY_AUTH_TOKEN=sntrys_YOUR_TOKEN_HERE

Upload the bundle and source map to Sentry:

node_modules/@sentry/cli/bin/sentry-cli sourcemaps upload \
  --debug-id-reference \
  --strip-prefix /path/to/project/root \
  index.android.bundle index.android.bundle.map

Troubleshooting

When generated source maps using this guide don’t seem to be correct, check the Contexts -> React Native -> Hermes Debug Info flag in the events. If the flag is true, this means the bundle shipped with the native application package was generated without Hermes source maps, and plain Metro (JS Core) source maps need to be used for the symbolication. Follow the JavaScript Core guide to upload the correct source maps.

Note that the debug information included in the Hermes bundle increases the size of the final shipped bundle, and it's recommended to enable the source maps during the native application build (even when uploaded later manually, as generating the Hermes source maps has a side effect of striping the debug information, saving it to the source map). For automatic source maps upload, follow the Manual Setup guide. The Sentry Xcode Scripts and Gradle Plugin automatically enable source maps. If you can't use the automatic upload scripts, enable source maps as described in the React Native Source Maps guide.

For more Hermes guides, see the Hermes Troubleshooting docs section.