Expo (Advanced)

Manually upload source maps for native Expo releases.

Sentry's React Native SDK works out of the box with Expo applications. To see readable stack traces in the product, you must upload source maps to Sentry. This guide explains how to manually upload source maps for Expo application releases.

For a guide on how to automatically upload source maps for Expo application releases or updates, see the Expo source maps docs.

To upload source maps, the Sentry Expo Plugin and the Sentry Metro Plugin need to be added to the Expo application.

To ensure bundles and source maps are automatically uploaded during the local and EAS native applications builds, add the @sentry/react-native/expo config plugin to the Expo application configuration:

Copied
{
  "expo": {
    "plugins": [
      [
        "@sentry/react-native/expo",
        {
          "url": "https://sentry.io/",
          "note": "Use SENTRY_AUTH_TOKEN env to authenticate with Sentry.",
          "project": "example-project",
          "organization": "example-org"
        }
      ]
    ]
  }
}

Add auth token to your environment:

Copied
# DO NOT COMMIT YOUR AUTH TOKEN
export SENTRY_AUTH_TOKEN=sntrys_YOUR_TOKEN_HERE

To ensure unique Debug IDs are assigned to the generated bundles and source maps, add the Sentry Metro Plugin to the configuration:

Copied
// const { getDefaultConfig } = require("expo/metro-config");
const {getSentryExpoConfig} = require('@sentry/react-native/metro');

// const config = getDefaultConfig(__dirname);
const config = getSentryExpoConfig(__dirname);

module.exports = config;

After the Sentry Expo Plugin and the Sentry Metro plugin are added to the application configuration, generate and upload Hermes source maps.

To generate a bundle and source maps for the native application release, use the following command:

Copied
# --entry-file node_modules/expo-router/entry.js \
npx expo export:embed \
  --entry-file node_modules/expo/AppEntry.js \
  --platform android \
  --dev false \
  --reset-cache \
  --bundle-output index.android.bundle \
  --sourcemap-output index.android.bundle.packager.map \
  --minify false

  • The actual command might differ depending on your application configuration. The above commands are the default commands used by Expo.
  • Bundle and source maps names can change the generated debug ID.
  • For custom entry file paths, the --entry-file parameter needs to be adjusted.

Compile Hermes bytecode bundle and source maps:

Copied
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:

Copied
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:

.env
Copied
SENTRY_ORG=example-org
SENTRY_PROJECT=example-project
SENTRY_AUTH_TOKEN=sntrys_YOUR_TOKEN_HERE

Upload the bundle and source maps to Sentry:

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

After the Sentry Expo Plugin and Sentry Metro plugin are added to the application configuration, generate and upload Javascript Core source maps.

To generate a bundle and source maps for the native application release, use the following command:

Copied
# --entry-file node_modules/expo-router/entry.js \
npx expo export:embed \
  --entry-file node_modules/expo/AppEntry.js \
  --platform android \
  --dev false \
  --reset-cache \
  --bundle-output index.android.bundle \
  --sourcemap-output index.android.bundle.map \
  --minify true

  • The actual command might differ depending on your application configuration. The above commands are the default commands used by Expo.
  • Bundle and source maps names can change the generated debug ID.
  • For custom entry file paths, the --entry-file parameter needs to be adjusted.

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

.env
Copied
SENTRY_ORG=example-org
SENTRY_PROJECT=example-project
SENTRY_AUTH_TOKEN=sntrys_YOUR_TOKEN_HERE

Upload the bundle and source map to Sentry:

Copied
npx sentry-cli sourcemaps upload \
  --strip-prefix /path/to/project/root \
  index.android.bundle index.android.bundle.map
Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").