Sentry SDK for React Native

The expo-stubs module provides mock implementations of expo-modules-core interfaces, specifically Package and ReactNativeHostHandler.

In a real Expo project, the Expo handler (android/expo-handler/) is compiled against the actual expo-modules-core library. It uses a ReactNativeHostHandler to capture native exceptions that are otherwise swallowed by Expo's bridgeless error handling mechanism (ExpoReactHostDelegate.handleInstanceException).

These stubs are used during unit testing in RNSentryAndroidTester to provide these necessary interfaces at compile time in environments where Expo is not present.

To start capturing errors and performance data, import the Sentry SDK and call Sentry.init. You must provide your project's dsn. You can also configure tracesSampleRate to control the volume of performance monitoring transactions (use 1.0 to capture 100%).

import * as Sentry from "@sentry/react-native";

Sentry.init({
  dsn: "__DSN__",

  // Set tracesSampleRate to 1.0 to capture 100%
  // of transactions for performance monitoring.
  // We recommend adjusting this value in production.
  tracesSampleRate: 1.0,
});

To regenerate the Replay stub classes and update the replay-stubs.jar file, run the build command from the root of the repository. This will recompile the classes and place the resulting JAR in packages/core/android/libs/replay-stubs.jar.

yarn build

If you need to update the stubbed classes, run the build command from the root of the repository. This will recompile the classes and generate a new JAR file located at packages/core/android/libs/expo-stubs.jar. You should then check this updated .jar file into your version control.

yarn build

If you need to reduce your Android bundle or APK size by excluding the sentry-android-replay module from your host app's classpath, you can do so in your android/build.gradle file.

Note that if you exclude this module, the React Native SDK requires the replay-stubs module to compile successfully. The stubs are provided as a compileOnly dependency, meaning they are available during compilation but are not included in the final runtime package, thus not affecting your app's size or runtime behavior.

subprojects {
    configurations.all {
        exclude group: 'io.sentry', module: 'sentry-android-replay'
    }
}

The SDK versions table in the documentation is automatically updated during releases. If you need to manually update the table to reflect the current versions of the bundled Sentry Android SDK, Sentry Cocoa SDK, or Sentry JavaScript SDK, run the update script from the repository root.

./scripts/update-sdk-versions-table.sh

Use the @sentry/expo-upload-sourcemaps command-line tool to upload JavaScript bundles and source maps from Expo builds to Sentry. This ensures that production error stack traces are symbolicated back to your original source code.

To use the tool, point it to the output directory produced by npx expo export or eas update (commonly named dist).

SENTRY_AUTH_TOKEN=<your-auth-token> \
npx @sentry/expo-upload-sourcemaps dist

If you are upgrading from the legacy react-native-sentry package (SDK versions < 1.0), you must follow a specific migration path:

1. Follow the official upgrade guide to handle breaking changes.
2. Follow the standard installation steps to integrate the new SDK.

If you already have @sentry/react-native installed in your project, the CLI is re-exposed under the binary name sentry-expo-upload-sourcemaps.

For new setups, the scoped form npx @sentry/expo-upload-sourcemaps is preferred.

The easiest way to install the Sentry SDK and configure your project is by using the Sentry Wizard CLI. This command automates the installation and setup process.

Run the following command in your terminal:

npx @sentry/wizard -s -i reactNative

The autoInitializeNativeSdk option (default: true) determines if the Sentry SDK initializes the native layer immediately upon JS initialization.

Warning: If you set this to false because you are managing a native SDK manually, ensure the native SDK is running before the JS Engine initializes. Otherwise, events occurring during startup might not be captured. Additionally, ensure the DSN used in both the React Native and native sides is identical.

When ReactNativeClient.init() is called, it triggers _initNativeSdk(). This process:

1. Sets up a native log listener if debug is enabled.
2. Configures Mobile Replay options (if the integration is present).
3. Calls NATIVE.initNativeSdk with merged options, including devServerUrl and defaultSidecarUrl.
4. Emits the afterInit event once the native initialization is complete.