Manual integration guide

Integrate BugSnag into your Expo app without using the CLI.

Installation

Install the @bugsnag/expo version that matches the Expo SDK version you are using:

expo install @bugsnag/expo@^52.0.0

Ensure the following @bugsnag/expo peer dependencies are installed:

expo install @react-native-community/netinfo \
expo-application \
expo-constants \
expo-crypto \
expo-device \
expo-file-system \
expo-secure-store

Support for the BugSnag Expo package (@bugsnag/expo) matches the policy of the Expo SDK: ~6 months of backwards compatibility, spanning approximately 3 major releases. For simplicity, the versioning of our package aligns with the version of the Expo SDK that it supports. A list of supported SDK versions can be found on the “Upgrading Expo SDK” page.

Expo SDK 43 and earlier

Support for versions for the Expo SDK 43 and earlier are in the 6.x and 7.x series of packages, you should install one of the following packages with your preferred npm client, adding it to your dependencies:

Basic configuration

We recommend putting your API key in app.json or app.config.js and having BugSnag pick it up automatically.

app.json / app.config.js

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

You can find your API key in Project Settings from your BugSnag dashboard.

App.js

Import and start the BugSnag client as early as possible:

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

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.

Promise rejections (Expo SDK 39-44 only)

Since Expo SDK 39, multiple versions of the promise library are listed in Expo’s dependencies, meaning that BugSnag can’t pick up the correct one to track promise rejections. A fix for this is in the latest versions of BugSnag Expo, but if you are using v44 or earlier you will need to use resolutions (in yarn) or overrides (in npm) in your package.json to ensure the correct version gets installed and so enable BugSnag promise rejection reporting:

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

Release tracking and source map upload

To notify BugSnag of releases and upload source maps so that you’ll see full stacktraces, you’ll need to add one of the following build hooks, depending on the type of Expo build you are using:

EAS Build

For EAS Build, we provide an Expo config plugin. To tell Expo to use this config plugin in your application builds, install the plugin as a devDependency as follows:

expo install @bugsnag/plugin-expo-eas-sourcemaps @bugsnag/source-maps -- -D

Then insert the following into your app.json/app.config.js:

{
  "expo": {
    "extra": {
      "bugsnag": {
        "apiKey": "YOUR_API_KEY"
      }
    },
    "plugins": ["@bugsnag/plugin-expo-eas-sourcemaps"]
  }
}

When using Expo 48+ you will need to add the following required additional configuration to the package.json file:

  "scripts": {
      ...
      "eas-build-on-success": "npx bugsnag-eas-build-on-success"
  }

Once this configuration is in place, every time you build a standalone app (eas build) your release will be reported to BugSnag, along with its source maps.

Monorepos

EAS Build is also supported for monorepos using Yarn workspaces, however additional configuration is required for our EAS sourcemaps plugin to prevent the packages being hoisted as they are accessed by the Android and iOS builds.

Insert the following into your <app_path>/package.json:

{
  "installConfig": {
    "hoistingLimits": "workspaces"
  }
}

Or with Yarn Classic (less than version 2):

{
  "workspaces": {
    "nohoist": ["@bugsnag/source-maps", "@bugsnag/plugin-expo-eas-sourcemaps"]
  }
}

Classic Expo build

If you are using the classic Expo build service, we provide a postPublish hook. To tell Expo to use this hook in your app, insert the following into your app.json/app.config.js:

{
  "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.