Manual integration guide

Integrate Bugsnag into your Expo app without using the CLI.

Installation

Install the @bugsnag/expo package with your preferred npm client, adding it to your dependencies:

# npm
npm install @bugsnag/expo

# yarn
yarn add @bugsnag/expo

Basic configuration

We recommend putting your API key in app.json and having Bugsnag pick it up automatically. In this location the postPublish hook will pick up too.

app.json

{
  "extra": {
    "bugsnag": {
      "apiKey": "YOUR_API_KEY"
    }
  }
}

import Bugsnag from '@bugsnag/expo'
Bugsnag.start()

You can find your API key in Project Settings.

Alternatively you can configure Bugsnag by providing your API key as a string:

import Bugsnag from '@bugsnag/expo'
Bugsnag.start('YOUR_API_KEY')

To specify any additional configuration options, supply an object instead:

Bugsnag.start({
  otherOptions: value
})

See configuration options for more information.

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 = Bugsnag.getPlugin('react').createErrorBoundary(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
}

When render errors happen, they will be reported to Bugsnag along with any React-specific info that was available at the time.

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

In the dashboard, you’ll see errors reported with extra debugging info in a “React” tab. For example:

Customizing the error boundary

The <ErrorBoundary /> component accepts some additional props:

• onError() – this allows you to pass in an onError callback which runs only for errors caught by the error boundary.
• FallbackComponent – by default the error boundary will attempt to re-render the child tree which may result in nothing being rendered at all. If you specify a <FallbackComponent/>, when an error happens Bugsnag will render this instead. This means you can display a user-friendly error state.
• clearError() – resets the state of the error boundary which will cause a re-render the child tree instead of the <FallbackComponent/>.

Post-publish hook

To notify Bugsnag of releases, and to upload source maps so that you’ll see full stacktraces, we provide a postPublish hook specifically for Expo.

To tell Expo to use this hook in your application, insert the following into your app.json:

{
  "expo": {
    "extra": {
      "bugsnag": {
        "apiKey": "YOUR_API_KEY"
      }
    },
    "hooks": {
      "postPublish": [
        {
          "file": "@bugsnag/expo/hooks/post-publish.js",
          "config": {
            /*

            For Bugsnag On-premise, the endpoints for each of
            the hook's components will need to be set:

            "sourceMapUploader": { "endpoint": "https://bugsnag-upload.example.com" },
            "buildReporter": { "endpoint": "https://bugsnag-builds.example.com" }

            */
          }
        }
      ]
    }
  }
}

Once this configuration is in place, every time you publish (expo publish) or build a standalone app (expo build:ios|android) your release will be reported to Bugsnag, along with its source maps.