Expo integration guide

Add Bugsnag to your Expo apps to report JavaScript errors.

New to Bugsnag? Create an account

This guide is for apps using Expo’s managed workflow on supported platforms. If you’re using the bare workflow or you’ve ejected your Expo app, you should follow our React Native guide.

This documentation is for version 7 of the Bugsnag JavaScript notifier. If you are using older versions, we recommend upgrading to the latest release using our Upgrade guide. Documentation for the previous release can be found on our legacy pages.

Installation and configuration

The easiest way to add Bugsnag to your Expo project is to use our CLI (macOS and Linux only). Alternatively you can follow the manual setup guide to install and configure the Bugsnag packages yourself.

# using npx (recommended)
npx bugsnag-expo-cli init

# using npm (if npx isn't available)
npm install --global bugsnag-expo-cli
bugsnag-expo-cli init

Note: npx (included with npm 5.2+) is a tool that lets you invoke command line tools from npm without installing them first.

This will install the @bugsnag/expo notifier, add some configuration to app.json and initialize Bugsnag in your application.

As of version 44, the Bugsnag Expo package (@bugsnag/expo) is versioned to match the Expo SDK version for which it provides support. This means that our package is actively supported while the equivalent version of the Expo SDK is supported. When support for an Expo SDK is dropped, we will also drop support for that version of @bugsnag/expo. A list of supported SDK versions can be found on the “Upgrading Expo SDK” page.

Capturing React render errors

The Bugsnag ErrorBoundary allows you to capture React render errors in your application. You can also use the FallbackComponent to display a custom error screen to your users:

// Start Bugsnag first...
Bugsnag.start({...})

// Create the error boundary...
const ErrorBoundary = Bugsnag.getPlugin('react').createErrorBoundary(React)

const ErrorView = () =>
  <div>
    <p>Inform users of an error in the component tree.</p>
  </div>

const App = () => {
  // Your main App component
}

export default () =>
  <ErrorBoundary FallbackComponent={ErrorView}>
    <App />
  </ErrorBoundary>

See our guide on capturing render errors to learn more about the ErrorBoundary and FallbackComponent.

TypeScript support

Type definitions are provided and will be picked up automatically by the TypeScript compiler when you import @bugsnag/expo.

Showing full stacktraces

Bugsnag supports showing full stacktraces for Expo release builds when built with either Expo Application Services (EAS) Build or the classic build service.

If you used our CLI tool (bugsnag-expo-cli) to install Bugsnag using the above instructions, it will have installed the necessary build hooks to report release builds and their source maps to Bugsnag. This will be triggered when eas build (or expo publish / expo build for classic builds) is executed.

Alternatively you can follow the manual setup guide to configure this yourself.

The Bugsnag plugin for EAS Build supports Expo SDK 45+ only.

Mapped stacktraces are not available for errors that happen in development as source maps are not generated by Expo development builds.

Reporting unhandled errors

After completing installation and basic configuration, unhandled exceptions and unhandled promise rejections will be reported and automatically appear on your Bugsnag dashboard.

In Expo SDK 39-40, unhandled promise rejections are not reported. This is due to multiple versions of the promise library in Expo’s dependencies, meaning that Bugsnag can’t pick up the correct one to track promise rejections. If you’re using yarn, you can add the following to your package.json to ensure only one version gets installed, meaning unhandled promise rejections can be reported:

  "resolutions": {
    "promise": "^8.0.3"
  }

Unhandled render errors will only be reported if you have wrapped your application in an error boundary.

Reporting handled errors

Sometimes it is useful to manually notify Bugsnag of a problem. To do this, call Bugsnag.notify(). For example:

try {
  something.risky()
} catch (e) {
  Bugsnag.notify(e)
}

When reporting handled errors, it’s often helpful to send custom diagnostic data or to adjust the severity of particular errors. For more information, see reporting handled errors.

Sending diagnostic data

Automatically captured diagnostics

As well as a full stacktrace for every exception, Bugsnag will automatically capture the following diagnostic data:

  • Full stack trace.
  • App state including running time and time in foreground.
  • Build information including name, version/build, release stage and whether the app is bundled as standalone.
  • Device specification including model, OS version and total memory.

For more information see Automatically captured data.

Attaching custom diagnostics

It can often be helpful to attach application-specific diagnostic data to error reports. This can be accomplished by setting a callback which will be invoked before any reports are sent to Bugsnag.

The following adds a map of data to the “company” tab on the Bugsnag dashboard for all captured events:

Bugsnag.start({
  onError: function (event) {
    event.addMetadata('company', {
      name: "Acme Co.",
      country: "uk"
    })
  }
})

For more information, see Customizing error reports.

Identifying users

In order to correlate errors with customer reports, or to see a list of users who experienced each error, it is helpful to capture and display user information on your Bugsnag dashboard.

You can set the user information of an error report using the user configuration property when Bugsnag starts or via an onError callback.

Bugsnag.start({
  onError: function (event) {
    event.setUser('3', 'bugs.nag@bugsnag.com', 'Bugs Nag')
  }
})

For information on doing so, see Adding user data.

Logging breadcrumbs

In order to understand what happened in your application before each crash, it can be helpful to leave short log statements that we call breadcrumbs. A configurable number of breadcrumbs are attached to each error report to help diagnose what events led to the error.

Automatically captured breadcrumbs

By default, Bugsnag captures the following events as breadcrumbs.

  • Errors
  • HTTP requests
  • Console logs, warnings, and errors
  • Orientation changes
  • App entering or exiting the foreground
  • Network state changes

For more information or to disable particular classes of automatic breadcrumb generation see configuration options.

Attaching custom breadcrumbs

You can use the leaveBreadcrumb method to log potentially useful events in your own applications:

Bugsnag.leaveBreadcrumb('Button clicked')

Bugsnag will keep track of the time and order of the breadcrumbs and show them on your dashboard. Additional data can also be attached to breadcrumbs by providing the optional metadata parameter.

For more information and examples for how custom breadcrumbs can be integrated, see Customizing breadcrumbs.

Tracking releases

Bugsnag will automatically associate your errors with the version of your application.

Using the provided Expo config plugin or postPublish hook, which are added as part of the installation instructions above, releases will be reported with build time metadata (source control revision, build time).

Session tracking

Bugsnag tracks the number of “sessions” that happen within your application. This allows you to compare stability scores between releases and helps you to understand the quality of your releases.

Sessions are captured and reported by default. This behavior can be disabled using the autoTrackSessions configuration option.

In Expo a new session is recorded each time the app starts.

For more information about manually controlling session tracking, see Capturing sessions.

Declaring feature flags and experiments

Monitor errors as you roll out features or run experiments and A/B tests by declaring your feature flag and experiment usage in the Bugsnag client. You can use the Features dashboard to identify whether these features have introduced errors into your app.

Bugsnag.addFeatureFlag('Checkout button color', 'Blue')
Bugsnag.addFeatureFlag('New checkout flow')

For more information, see Feature flags & experiments.

Next steps

  • View @bugsnag/expo, the library powering Bugsnag’s Expo error reporting, on GitHub
  • Get support for your questions and feature requests