Add BugSnag to your Expo apps to report JavaScript errors.
This documentation is for version 6 of the BugSnag JavaScript notifier. We recommend upgrading to the latest release using our Upgrade guide. Documentation for the current release can be found here.
New to BugSnag? Create an account
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.
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.
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.
Type definitions provided and will be picked up automatically by the TypeScript compiler when you import @bugsnag/expo.
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.
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.
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.
As well as a full stacktrace for every exception, BugSnag will automatically capture the following diagnostic data:
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.
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.
By default, BugSnag captures the following events as breadcrumbs.
For more information or to disable particular classes of automatic breadcrumb generation see configuration options.
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
})
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'
}
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).
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 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.
@bugsnag/js, the library powering BugSnag’s JavaScript error reporting, on GitHub