Integrating Instabug with Expo

Overview

Instabug supports modern Expo development. The recommended way to install Instabug is by using our Expo Plugin, which automatically handles native project configuration and automates the sourcemap uploading process for your standard builds.

📘

Note

The Instabug SDK is not supported in the Expo Go app. You will need to create a development build or use a simulator/physical device.

Recommended Setup: Using the Expo Plugin

This is the simplest and most robust way to integrate Instabug into an Expo project.

Step 1: Install the SDK

In your project directory, run the following command to install the Instabug SDK:

npm install instabug-reactnative

Or, if you prefer using Yarn:

yarn add instabug-reactnative

Step 2: Configure the Expo Plugin

Add the instabug-reactnative plugin to the plugins array in your app.json file.

{
  "expo": {
    "plugins": [
      [
        "instabug-reactnative",
        {
          "addScreenRecordingBugReportingPermission": true //check note below
        }
      ]
    ]
  }
}

The addScreenRecordingBugReportingPermission is an optional helper that automatically adds the required microphone and photo library permissions on iOS and the foreground service permission on Android for the screen recording feature.

Step 3: Rebuild Your App

After adding the plugin, you will need to rebuild your app's native directories for the changes to take effect. Run the following command:

npx expo prebuild

This command will modify your ios and android directories to include the necessary Instabug configurations.

Automatic Sourcemap Uploads

A key benefit of using the Expo Plugin is that it automatically handles sourcemap uploads for all your standard Expo builds (eas build). By adding the plugin to your app.json, it will detect your builds and upload the correct sourcemaps to Instabug with no additional configuration required.

📘

Note

This automatic process applies to standard builds only. For Expo Updates (OTA), you must manually upload sourcemaps using our CLI. See our Over-the-Air (OTA) Updates Guide for more details.

Using Instabug

To start using Instabug, import and initialize the SDK in your app’s main file (e.g. App.js).

import Instabug, { InvocationEvent } from 'instabug-reactnative';

Instabug.init({
  token: 'APP_TOKEN',
  invocationEvents: [InvocationEvent.shake],
});

You can find your app token by selecting SDK Integration in the Settings menu from your Instabug dashboard.

Legacy: Using a Custom Development Client

For older managed workflows that do not use the Expo plugin system, you will need to use Expo’s custom development client.

1. Run npx expo install expo-dev-client.
2. Modify your package.json scripts to use the --dev-client flag for the start command.
   JSON

   "scripts": {
     "start": "expo start --dev-client",
     "android": "expo run:android",
     "ios": "expo run:ios"
   }
   

3. Proceed with the Instabug SDK installation and initialization as described above.