bugscreen
HomeDocsReact Native

Setup

v1.9.0

Install and initialize the SDK for your testers.

Installation

Bare React Native

Install the package, then install the iOS pods:

bash
npm install @bugscreen/react-native
# or: yarn add @bugscreen/react-native
# or: pnpm add @bugscreen/react-native
bash
cd ios && bundle exec pod install

Requires React Native 0.74+, iOS 15+ and Android API 24+. Use any higher minimum required by your React Native version.

Expo

Install BugScreen and the development client. Expo Go is not supported.

bash
npx expo install @bugscreen/react-native expo-dev-client

Add the config plugin to app.json:

json
{
  "expo": {
    "plugins": [
      [
        "@bugscreen/react-native",
        { "photoLibraryUsageDescription": "Used to attach screenshots to bug reports." }
      ]
    ]
  }
}

The Photos description is optional; the example shows its default. An existing description in your app takes precedence.

Build and install a development client, then start Metro:

bash
npx eas-cli@latest build:configure
# Set developmentClient: true in the development profile.
npx eas-cli@latest build --profile development --platform android
# For iOS, use --platform ios.
npx expo start --dev-client
  • For local builds, use npx expo run:android or npx expo run:ios.
  • Rebuild the development client after updating BugScreen or changing plugin options.

Compatibility

  • Supports the New Architecture. Install iOS dependencies with CocoaPods.
  • Current frameworks: React Native 0.88 and Expo SDK 58 (checked 20 October 2026).
  • Builds are verified on React Native 0.86; the Expo example uses SDK 57. React Native 0.88 and Expo 58 builds have not been verified.

Get your SDK API key

  1. Open Apps in the console. Select your app, or choose New app and then Create app.
  2. Open the SDK tab. An organisation admin can select Reveal beside SDK API key and copy the key.
  3. Replace fb_your_api_key_here in the initialization example below with that key.
Open the console

Setup

Configure BugScreen once at startup, before calling other SDK methods:

tsx
import { useEffect } from 'react';
import { BugScreen } from '@bugscreen/react-native';

export default function App() {
  useEffect(() => {
    if (!__DEV__) return;

    BugScreen.configure({
      apiKey: 'fb_your_api_key_here',
      screenshotDetection: true,
      debug: __DEV__,
    }).catch((err) => console.warn('BugScreen configure failed', err));
  }, []);

  return null; // Replace with your app UI.
}

Use __DEV__ for local debug builds or your own flag for QA builds. This prevents initialization; it does not remove the SDK from the app binary.

Starting and stopping

  • Await configure() before logging, setting context or opening the reporter.
  • isConfigured() returns Promise<boolean>. shutdown() returns Promise<void> and stops screenshot detection.
  • After shutdown(), call configure() again before using BugScreen.
typescript
import { BugScreen } from '@bugscreen/react-native';

async function stopBugScreen() {
  if (await BugScreen.isConfigured()) {
    await BugScreen.shutdown();
  }
}

configure() rejects with E_INVALID_API_KEY if a non-empty key does not start with fb_ or is too short. Handle errors without logging the key.

Configure screenshot permissions and send your first screenshot report.

Usage

Configuration

Use BugScreen from your assistant with the MCP setup guide.