Expo (Advanced)

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.

Prerequisities

• Sign up for an account
• Migrate from sentry-expo to @sentry/react-native
• Set up Sentry React Native SDK version 5.16.0-alpha.4 or newer

Common Setup

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

Add the Sentry Expo Plugin

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:

{
  "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:

# DO NOT COMMIT YOUR AUTH TOKEN
export SENTRY_AUTH_TOKEN=sntrys_YOUR_TOKEN_HERE

Add the Sentry Metro Plugin

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

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

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

module.exports = config;

Manual Upload for Hermes Release

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

Generate Bundle

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

# --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

Notes

• 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 Bytecode

Compile Hermes bytecode bundle and source maps:

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:

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

Upload Source Maps

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 maps to Sentry:

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

Manual Upload for JSC Release

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

Generate Bundle

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

# --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

Notes

• 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.

Upload Source Maps

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:

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