Using Sentry

{
  "expo": {
    "plugins": [
      [
        "@sentry/react-native/expo",
        {
          "organization": "sentry org slug, or use the `SENTRY_ORG` environment variable",
          "project": "sentry project name, or use the `SENTRY_PROJECT` environment variable",
          // If you are using a self-hosted instance, update the value of the url property
          // to point towards your self-hosted instance. For example, https://self-hosted.example.com/.
          "url": "https://sentry.io/"
        }
      ]
    ]
  }
}

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

// This replaces `const config = getDefaultConfig(__dirname);`
const config = getSentryExpoConfig(__dirname);

module.exports = config;

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

Sentry.init({
  dsn: 'YOUR DSN HERE',
  debug: true, // If `true`, Sentry will try to print out useful debugging information if something goes wrong with sending the event. Set it to `false` in production
});

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

// Your App component here

export default Sentry.wrap(App);

import { Button } from 'react-native';

// Inside some component
<Button title="Press me" onPress={() => { throw new Error('Hello, again, Sentry!'); }}/>

Usage with Expo Router

If your app uses Expo Router, then you can configure Sentry to automatically capture the current route and pass it along with your error reports. To set this up, configure Sentry in the Root Layout route and add the navigation integration.

import { Slot, useNavigationContainerRef } from 'expo-router';
import { useEffect } from 'react';
import * as Sentry from '@sentry/react-native';
import { isRunningInExpoGo } from 'expo';

// Construct a new integration instance. This is needed to communicate between the integration and React
const navigationIntegration = Sentry.reactNavigationIntegration({
  enableTimeToInitialDisplay: !isRunningInExpoGo(),
});

Sentry.init({
  dsn: 'YOUR DSN HERE',
  debug: true, // If `true`, Sentry will try to print out useful debugging information if something goes wrong with sending the event. Set it to `false` in production
  tracesSampleRate: 1.0, // Set tracesSampleRate to 1.0 to capture 100% of transactions for tracing. Adjusting this value in production.
  integrations: [
    // Pass integration
    navigationIntegration,
  ],
  enableNativeFramesTracking: !isRunningInExpoGo(), // Tracks slow and frozen frames in the application
});

function RootLayout() {
  // Capture the NavigationContainer ref and register it with the integration.
  const ref = useNavigationContainerRef();

  useEffect(() => {
    if (ref?.current) {
      navigationIntegration.registerNavigationContainer(ref);
    }
  }, [ref]);

  return <Slot />;
}

// Wrap the Root Layout route component with `Sentry.wrap` to capture gesture info and profiling data.
export default Sentry.wrap(RootLayout);

Usage with EAS Build

Ensure that SENTRY_AUTH_TOKEN is set in your build environment, and Sentry will automatically upload source maps for you. If you use environment variables rather than properties in your app config, ensure that those are set as well.

Using the above instructions, no additional work is needed to integrate Sentry into your project when using EAS Build.

Usage with EAS Update

After running eas update, upload the source maps to Sentry:

That's it! Errors for your updates will now be properly symbolicated in Sentry.

Do you want to append additional update-related metadata to error reports?

Configuring Sentry to tag your scope with information about your update allows you to see errors happening on certain updates in the Sentry dashboard.

Add the following snippet in the global scope as early as possible in your application's lifecycle.

import * as Sentry from '@sentry/react-native';
import * as Updates from 'expo-updates';

const manifest = Updates.manifest;
const metadata = 'metadata' in manifest ? manifest.metadata : undefined;
const extra = 'extra' in manifest ? manifest.extra : undefined;
const updateGroup = metadata && 'updateGroup' in metadata ? metadata.updateGroup : undefined;

Sentry.init({
  // dsn, release, dist, etc...
});

const scope = Sentry.getGlobalScope();

scope.setTag('expo-update-id', Updates.updateId);
scope.setTag('expo-is-embedded-update', Updates.isEmbeddedLaunch);

if (typeof updateGroup === 'string') {
  scope.setTag('expo-update-group-id', updateGroup);

  const owner = extra?.expoClient?.owner ?? '[account]';
  const slug = extra?.expoClient?.slug ?? '[project]';
  scope.setTag(
    'expo-update-debug-url',
    `https://expo.dev/accounts/${owner}/projects/${slug}/updates/${updateGroup}`
  );
} else if (Updates.isEmbeddedLaunch) {
  // This will be `true` if the update is the one embedded in the build, and not one downloaded from the updates server.
  scope.setTag('expo-update-debug-url', 'not applicable for embedded updates');
}

Once configured, information about the associated update will show up in an error's tag section:

sentry-expo has been merged into @sentry/react-native and is now deprecated. We recommend upgrading to SDK 50 to use @sentry/react-native for the best experience. If you're already using sentry-expo, learn how to migrate.

import * as Sentry from 'sentry-expo';

Sentry.init({
  dsn: 'YOUR DSN HERE',
  enableInExpoDevelopment: true,
  debug: true, // If `true`, Sentry will try to print out useful debugging information if something goes wrong with sending the event. Set it to `false` in production
});

// Access any @sentry/react-native exports via:
// Sentry.Native.*

// Access any @sentry/browser exports via:
// Sentry.Browser.*

// The following example uses `captureException()` from Sentry.Native.* to capture errors:
try {
  // your code
} catch (error) {
  Sentry.Native.captureException(error);
}

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

Sentry.init({
  dsn: 'YOUR DSN',
});

{
  "expo": {
    %%placeholder-start%%...%%placeholder-end%%
    "hooks": {
      "postPublish": [
        {
          "file": "sentry-expo/upload-sourcemaps",
          "config": {
            "organization": "sentry org slug, or use the `SENTRY_ORG` environment variable",
            "project": "sentry project name, or use the `SENTRY_PROJECT` environment variable"
          }
        }
      ]
    }
  }
}

{
  "expo": {
    "plugins": ["sentry-expo"]
    %%placeholder-start%%... %%placeholder-end%%
  }
}

Source maps

With the postPublish hook in place, now all you need to do is run expo-cli publish and the source maps will be uploaded automatically. We automatically assign a unique release version for Sentry each time you hit publish, based on the version you specify in app.json and a release id on our backend -- this means that if you forget to update the version but hit publish, you will still get a unique Sentry release.

Uploading source maps at build time

With expo-updates, release builds of both Android and iOS apps will create and embed a new update from your JavaScript source at build-time. This new update will not be published automatically and will exist only in the binary with which it was bundled. Since it isn't published, the source maps aren't uploaded in the usual way like they are when you run expo-cli publish (actually, we are relying on Sentry's native scripts to handle that). Because of this you have some extra things to be aware of:

• Your release will automatically be set to Sentry's expected value- ${bundleIdentifier}@${version}+${buildNumber} (iOS) or ${androidPackage}@${version}+${versionCode} (Android).
• Your dist will automatically be set to Sentry's expected value: ${buildNumber} (iOS) or ${versionCode} (Android).
• The configuration for build time source maps comes from the android/sentry.properties and ios/sentry.properties files. For more information, see Sentry's documentation. Manual configuration is only required for bare projects, the sentry-expo config plugin handles it otherwise.
• Configuration for expo publish and npx expo export for projects is done via app.json, whether using bare workflow or not.

Skipping or misconfiguring either of these can lead to invalid source maps, and you won't see human-readable stacktraces in your errors.

Uploading source maps for updates

If you're using EAS Update, or if you're self-hosting your updates (this means you run npx expo export manually), you need to take the following steps to upload the source maps for your update to Sentry:

• Run eas update. This will generate a dist directory in your project root, which contains your JavaScript bundles and source maps. This command will also output the 'Android update ID' and 'iOS update ID' that we'll need in the next step.
• Copy or rename the bundle names in the dist/bundles directory to match index.android.bundle (Android) or main.jsbundle (iOS).
• Next, you can use the Sentry CLI to upload your bundles and source maps:
  • release name should be set to ${bundleIdentifier}@${version}+${buildNumber} (iOS) or ${androidPackage}@${version}+${versionCode} (Android), so for example com.domain.myapp@1.0.0+1.
  • dist should be set to the Update ID that eas update generated.

For more information, see Sentry's instructions for uploading the bundle and source maps.

The steps above define a new 'dist' on Sentry, under the same release as your full app build, and associate the source maps with this new dist. If you want to customize this behavior, you can pass in your own values for release and dist when you initialize Sentry in your code. For example:

import * as Sentry from 'sentry-expo';
import * as Updates from 'expo-updates';

Sentry.init({
  dsn: 'YOUR DSN',
  release: 'my release name',
  dist: 'my dist',
});

These values should match the values you pass to the sentry-cli when uploading your source maps.

Testing Sentry

When building tests for your application, you want to assert that the right flow-tracking or error is being sent to Sentry, but without really sending it to Sentry servers. This way you won't swamp Sentry with false reports during test running and other CI operations.

sentry-testkit enables Sentry to work natively in your application, and by overriding the default Sentry transport mechanism, the report is not really sent but rather logged locally into memory. In this way, the logged reports can be fetched later for your own usage, verification, or any other use you may have in your local developing/testing environment.

For more information on how to get started, see sentry-testkit documentation.

If you're using jest, make sure to add @sentry/.* and sentry-expo to your transformIgnorePatterns.

Error reporting semantics

To ensure that errors are reported reliably, Sentry defers reporting the data to their backend until the next time you load the app after a fatal error rather than trying to report it upon catching the exception. It saves the stacktrace and other metadata to AsyncStorage and sends it immediately when the app starts.

Disabled by default in dev

Unless enableInExpoDevelopment: true is set, all your dev/local errors will be ignored and only app releases will report errors to Sentry. You can call methods like Sentry.Native.captureException(new Error('Oops!')) but these methods will be no-op.

Troubleshooting

import * as Sentry from 'sentry-expo';
import Constants from 'expo-constants';

Sentry.init({
  tracesSampleRate: 1.0,
  integrations: [
    new Sentry.Native.ReactNativeTracing({
      shouldCreateSpanForRequest: url => {
        return !__DEV__ || !url.startsWith(`http://${Constants.expoConfig.hostUri}/logs`);
      },
    }),
  ],
});