@observerkit/react-native

ObserverKit SDK for React Native: automatic error reporting and captureException, with source map support via @observerkit/metro.

Install

npm install @observerkit/react-native

Usage

Initialize once, as early as possible (before AppRegistry.registerComponent):

import * as ObserverKit from "@observerkit/react-native"

ObserverKit.init({
  projectKey: "YOUR_PROJECT_KEY",
  environment: "production",
})

Unhandled JS errors and unhandled promise rejections are reported automatically. Report handled errors yourself:

try {
  await syncData()
} catch (error) {
  ObserverKit.captureException(error, { metadata: { screen: "Settings" } })
}

Options

| Option | Default | Description | | --- | --- | --- | | projectKey | required | Your ObserverKit project key | | autoCapture | true | Install global error and rejection handlers | | endpoint | ObserverKit cloud | Ingest endpoint URL | | environment | undefined | Environment tag on every event | | service | undefined | Service name to distinguish apps sharing one project, e.g. in a monorepo. Auto-creates the service on first event |

Device context (os, osVersion, devBuild) is attached to every event under metadata.device.

Notes

• Unhandled promise rejection capture uses the Hermes rejection tracker and replaces the default dev warning.
• With an eventStore configured (AsyncStorageStore or MmkvStore), fatal errors are persisted to disk before the app terminates and are delivered automatically on next launch. Without one, the app may terminate before the report finishes sending.

Android native crashes and ANRs

When the native module is linked (bare React Native, or Expo with a development build / prebuild, not Expo Go), JVM crashes and ANRs are captured in addition to JS errors, on by default with no extra setup. Pass nativeCrashReporting: false to init to opt out. Native crash reporting also requires autoCapture to be enabled, so passing autoCapture: false disables it too. ANR detection requires Android 11 (API 30) or newer.

Release builds run through R8/ProGuard, so stack traces are obfuscated unless a mapping file is uploaded. With the Expo config plugin (@observerkit/metro/expo), the upload is automatic: a Gradle hook uploads mapping.txt after the R8 minify task, keyed by versionName and versionCode. Bare React Native uploads it manually with the CLI: observerkit-upload --mapping android/app/build/outputs/mapping/release/mapping.txt --version-name 1.2.0 --version-code 42. The server deobfuscates and groups JVM crash and ANR frames using the uploaded mapping.

Source maps

Readable production stack traces need @observerkit/metro: a Metro config wrapper that injects debug IDs plus an upload step for your native builds. See that package's README.