Expo integration guide

Add Bugsnag to your Expo apps to report JavaScript errors.

New to Bugsnag? Create an account

Note for bare Expo apps

If you’re using the bare workflow or you’ve ejected your Expo app, you should follow the React Native guide.

You should continue with this guide if you’re using Expo’s managed workflow.

Installation and configuration

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

# 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.

Capturing React render errors

An error boundary component is included which you can use to wrap your application. When render errors happen, they will be reported to Bugsnag along with any React-specific info that was available at the time.

To catch all render errors in your application and show a custom error screen to your users, follow this example:

const ErrorBoundary = bugsnagClient.getPlugin('react')

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

class App extends React.Component {
  // Your main app component
}

class ErrorView extends React.Component {
  // This component will be displayed when an error boundary catches an error
}

See React’s documentation on Error Boundaries to find out more.

TypeScript support

Type definitions 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.

Using the provided postPublish hook, every time you publish a JS bundle with expo publish or build a standalone app with expo build:ios|android, your release will be reported to Bugsnag, along with its source maps.

If you used the CLI but didn’t choose to install the postPublish hook, you can add it with the following command:

npx bugsnag-expo-cli add-hook

Alternatively you can follow the manual setup guide.

Note: full stacktraces are not shown for errors that happen in development.

Reporting unhandled errors

After completing installation and basic configuration, unhandled exceptions and unhandled promise rejections will be automatically reported.

Note: unhandled render errors will only be reported in development 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 bugsnagClient.notify(). For example:

try {
  something.risky()
} catch (e) {
  bugsnagClient.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:

  • App version (including native version if bundled as a standalone app)
  • How long the app has been running at the time of the error
  • Whether the app was in the foreground at the time of the error, and if so, the duration it spent in the foreground
  • Whether the app is running inside the Expo client or standalone
  • OS name and version
  • Hardware model, manufacturer and version (iOS only)
  • Device ID

Custom diagnostics

Error reports have a metaData property where arbitrary data can be attached.

Top-level properties of metaData will render as tabs in the Bugsnag dashboard. Custom metaData can be supplied globally:

bugsnagClient.metaData = {
  company: {
    name: "Acme Co.",
    country: "uk"
  }
}

For additional options on attaching custom metaData, see customizing error reports.

Leaving breadcrumbs

Breadcrumbs allow you to see a log of actions that led up to an error. Error reports automatically include breadcrumbs for the last 20 events which occurred.

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 can use the leaveBreadcrumb(message, metadata) method to log potentially useful events in your own applications:

bugsnagClient.leaveBreadcrumb('User clicked a button')

The time and order of breadcrumbs will be recorded and shown in the dashboard.

The metadata argument is optional and can be used to attach to additional information to a breadcrumb. This can be a one-level-deep key → value mapping object:

bugsnagClient.leaveBreadcrumb('Order summary requested', {
  amount: 4500,
  currency: 'EUR',
  nItems: 21
})

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 provide or modify the user information of an error report by supplying the user option to a notify call, or using a beforeSend callback to modify report.user. For information on doing so, see customizing error reports.

You can also attach user info directly on the bugsnagClient instance. This will then be sent along with all subsequent errors.

// Attach to the client object
bugsnagClient.user = {
  id: '3',
  name: 'Bugs Nag',
  email: 'bugs.nag@bugsnag.com'
}

Tracking releases

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

Using the provided postPublish hook, releases will be reported with build time metadata (source control revision, build time, JS bundle revision id).

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 behaviour can be disabled using the autoCaptureSessions configuration option.

In Expo, by default a new session is reported each time the app starts. If you want control over what is deemed a session, you can switch off automatic session tracking with the autoCaptureSessions option, and call bugsnagClient.startSession() when appropriate for your application.

Next steps