React Native

Catch JavaScript errors in your iOS and Android apps with @sentry/react-native. Upload source maps and Hermes stack traces point at your original code, with the device, OS and app version on every issue.

1. Install the SDK

npm install @sentry/react-native
cd ios && pod install

2. Initialize it as early as you can

At the top of your app's entry file, then wrap your root component so React errors are caught too:

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

Sentry.init({
  dsn: "https://<key>@uncaught.thistinct.tools/<project-id>",
  environment: "production"
})

export default Sentry.wrap(App)

The SDK sets the release to [email protected]+42 from your app's bundle ID, version and build number. Pass release and dist to Sentry.init to use your own.

3. Check that it works

Add a button to any screen, tap it, and the error shows up as an issue:

<Button title="Send a test error" onPress={() => { throw new Error("Hello from React Native") }} />

Add context

Sentry.setUser({ id: currentUser.id, email: currentUser.email })
Sentry.setTag("plan", currentUser.plan)

Source maps

Release builds run on Hermes bytecode, where every stack frame is on line 1 of main.jsbundle or index.android.bundle. Uncaught turns those frames back into your files, lines and function names with the source maps from your build, and iOS and Android reports of the same error become one issue.

1. Add Debug IDs to your bundles

Sentry's Metro plugin writes the same ID into each bundle and its map, so they match whatever the release:

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

module.exports = withSentryConfig(getDefaultConfig(__dirname))

2. Upload from your builds

The SDK's build steps call sentry-cli for you. Point it at Uncaught with an API token, in a sentry.properties file in both ios and android. Keep it out of git, or set SENTRY_URL, SENTRY_ORG, SENTRY_PROJECT and SENTRY_AUTH_TOKEN in CI instead.

defaults.url=https://uncaught.thistinct.tools/
defaults.org=your-organization
defaults.project=your-project
auth.token=uncaught_…

On Android, add this line to android/app/build.gradle:

apply from: "../../node_modules/@sentry/react-native/sentry.gradle"

On iOS, change the Bundle React Native code and images build phase in Xcode to run the SDK's script:

set -e
WITH_ENVIRONMENT="../node_modules/react-native/scripts/xcode/with-environment.sh"
SENTRY_XCODE="../node_modules/@sentry/react-native/scripts/sentry-xcode.sh"
/bin/sh -c "$WITH_ENVIRONMENT \"/bin/sh $SENTRY_XCODE ../node_modules/react-native/scripts/react-native-xcode.sh\""

With Expo

Use the Expo config for Metro, and add the SDK's plugin to app.json:

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

module.exports = getSentryExpoConfig(__dirname)

{
  "expo": {
    "plugins": [
      ["@sentry/react-native/expo", {
        "url": "https://uncaught.thistinct.tools/",
        "organization": "your-organization",
        "project": "your-project"
      }]
    ]
  }
}

Set SENTRY_AUTH_TOKEN in your EAS secrets. Local builds pick the upload up the same way, and for expo export run npx sentry-expo-upload-sourcemaps dist afterwards, with the environment variables above.

With sentry-cli

For a custom build, upload the bundle and its final map (composed with the Hermes one) yourself:

npx @sentry/cli sourcemaps upload \
  --release "[email protected]+42" --dist 42 \
  --bundle index.android.bundle --bundle-sourcemap index.android.bundle.map

See Releases and sentry-cli for more on tokens and releases.

What's covered

Uncaught handles the JavaScript errors in your app. Crashes in native code on iOS and Android still arrive, but as they are: minidumps are ignored, and native frames aren't symbolicated. Uncaught doesn't take dSYMs or ProGuard mappings yet, so leave out Sentry's Upload Debug Symbols build phase on iOS and its Android Gradle plugin.