Using Sentry

Edit this page

A guide on installing and configuring Sentry for crash reporting.

Sentry is a crash reporting platform that provides you with real-time insight into production deployments with info to reproduce and fix crashes.

It notifies you of exceptions or errors that your users run into while using your app and organizes them for you on a web dashboard. Reported exceptions include stacktraces, device info, version, and other relevant context automatically. You can also provide additional context that is specific to your application such as the current route and user id.

What you'll learn

This guide covers three main aspects of integrating Sentry with your Expo projects:

Install and configure Sentry in your React Native app
Using Sentry with EAS:
- EAS Build for building your app
- EAS Update for over-the-air updates
Setting up the Sentry-Expo integration to view crash reports and session replays directly in your Expo dashboard

Platform compatibility

Android Device	Android Emulator	iOS Device	iOS Simulator	Web

Install and configure Sentry

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.

Sign up for a Sentry account and create a project

Before proceeding with installing Sentry, you'll need to make sure you have created a Sentry account and project:

1.1

Sign up for Sentry (the free tier supports up to 5,000 events per month), and create a project in your Dashboard. Take note of your organization slug, project name, and DSN as you'll need them later:

organization slug is available in your Organization settings tab
project name is available in your project's Settings > Projects tab (find it in the list)
DSN is available in your project's Settings > Projects > Project name > Under SDK Setup section > Client Keys (DSN) tab.

1.2

Go to the Developer Settings > Auth Tokens page and create a new Organization Auth Token. The token is automatically scoped for Source Map Upload and Release Creation. Save it.

Once you have each of these: organization slug, project name, DSN, and auth token, you're all set to proceed.

Use the Sentry wizard to set up your project

The easiest way to set up Sentry in your Expo project is to use the Sentry wizard. This tool will automatically configure your project with the right settings.

Run the following command in your project directory:

Terminal

- npx @sentry/wizard@latest -i reactNative

The wizard will:

Install the required dependencies
Configure your project to use Sentry
Set up the Metro configuration automatically
Add the necessary initialization code to your app

Follow the prompts in the wizard to complete the setup process. The wizard will guide you to log in to your Sentry account and fetch all the correct information regarding your project.

Verify the configuration

Create a new release build of your app and verify that it uploads source maps correctly. You may want to add a button in your app to test that it is working and sourcemaps are wired up as expected, for example:

import { Button } from 'react-native';

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

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:

Terminal

# Pass in the "dist" directory generated by `eas update` to the upload script

- npx sentry-expo-upload-sourcemaps dist

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

Do you want to publish an update and the sourcemaps in one command?

You can chain the commands together with && to publish an update and upload the sourcemaps in one step:

Terminal

- eas update --branch <branch> && npx sentry-expo-upload-sourcemaps dist

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 integration with Expo dashboard

The Sentry integration with Expo allows you to view crash reports and Session Replays for your Expo app deployments directly within your Expo dashboard. This integration provides a direct link to Sentry stack traces with full context, session replays, and debugging capabilities.

Install

Sentry owner, manager, or admin permissions are required to install this integration.

Log in to you Expo account and open Account settings > Overview.
Under Connections and click Connect next to Sentry.
Log in to your Sentry account and accept the integration into your organization. You will be redirected back to Account settings.

Link your project

After connecting your accounts, you need to link your EAS Project to your Sentry Project:

Open Projects > [Your Project] > Configuration > Project settings in EAS.
Click Link and select your Sentry Project from the dropdown.

Usage

To see your Sentry data in Expo dashboard:

Open Projects > [Your Project] > Updates > Deployments > [Deployment] to view Sentry data from a Release.

With this integration, you can:

View crash reports directly in your Expo dashboard
Access Session Replays to see exactly what happened before an error occurred
Get detailed stack traces with full context
Navigate seamlessly between EAS and Sentry for debugging

Learn more about Sentry

Sentry does more than just catch fatal errors, learn more about how to use Sentry from their JavaScript usage documentation.