@unhandled/react-native
v0.5.6
Published
Unhandled SDK for React Native and Expo: errors, offline queue, screen and network spans, Hermes source maps
Readme
@unhandled/react-native
Unhandled SDK for Expo and React Native apps. It reports uncaught JS errors and unhandled promise rejections, keeps everything in an on-disk queue until the device is online, records screen changes, network calls and the cold start as spans, and uploads the Hermes source map of every release build so stack traces point at your source.
It posts OTLP/HTTP JSON to the ingest endpoint in your DSN. It needs Expo modules (expo-constants, expo-file-system), which every Expo app has and a bare React Native app gets from npx install-expo-modules.
Install
npx expo install @unhandled/react-native expo-constants expo-file-system{ "expo": { "plugins": [["@unhandled/react-native", { "service": "my-app-ios" }]] } }import { init } from '@unhandled/react-native'
import { useNavigationContainerRef } from 'expo-router'
import { useEffect } from 'react'
const unhandled = init({ dsn: process.env.EXPO_PUBLIC_UNHANDLED_DSN ?? '', environment: 'production' })
export default function RootLayout() {
const navigation = useNavigationContainerRef()
useEffect(() => unhandled.registerNavigationContainer(navigation), [navigation])
// your layout
}Identify the signed-in person with unhandled.identify(user.id, { plan: 'pro' }), update their profile with unhandled.setUserProperties({ seats: 3 }) and call unhandled.reset() on sign-out. identify sends a profile update and makes { id } the user on later errors (a setUser() with the same id keeps its email and name). The id lives in memory, so call it again after each launch. Invalid ids and properties are dropped silently. React Native sends no page views or custom events, only experiment exposures and revenue. unhandled.getVariant('paywall', ['control', 'annual-first']) returns the identified user's variant, the same one every SDK picks, and records an experiment_exposure once per variant per app run; before identify() it returns the first variant and records nothing, so a user can move to their own variant when they sign in. unhandled.trackExposure(experiment, variant) records a variant you assigned yourself, and does nothing before identify(). Revenue: unhandled.trackRevenue({ amount: 1999, currency: 'usd', product: 'pro', subscription: { id: 'sub_1', interval: 'month' } }) records a purchase, renewal or refund. amount is an integer in the currency's minor unit (negative for a refund), and invalid input is dropped silently. Pass the payment provider's charge id as id so a retried call counts once. The name revenue is reserved for trackRevenue.
User feedback: unhandled.captureFeedback({ message: 'Checkout failed', email: '[email protected]' }) validates now, returns { ok: true } or { ok: false, error: 'invalid' | 'inactive', message }, and queues the note for POST /v1/feedback; it survives restarts and retries offline. It attaches the last error reported in the past hour unless you pass occurrenceId. There is no feedback widget in React Native; build your own form.
An empty DSN gives an inactive client that sends nothing. Release builds upload main.jsbundle.map when UNHANDLED_API_KEY holds a deploy key in the build environment.
Full guide: https://unhandled.net/docs/sdks/react-native
For AI agents
A coding agent can install this package, check that its data arrives and fix the errors it reports through the Unhandled MCP server at https://unhandled.net/mcp. In Claude Code, the Unhandled plugin adds that server plus skills for instrumenting a service, fixing a production error with a failing test first and verifying a deploy:
claude plugin marketplace add treboryx/unhandled
claude plugin install unhandled@unhandledCodex, Cursor, Gemini CLI and other agents connect to the same URL. Coding agents has the setup for each one and an AGENTS.md section to add to your repository.
