@tillstack/react-native

TillPulse observability SDK for React Native — JS and native crash reporting, unclean-exit detection, cold-start and frame-jank performance, transactions, breadcrumbs, sessions, an offline queue and on-device PII scrubbing.

Install

npm install @tillstack/react-native
# or: pnpm add @tillstack/react-native

react (>=18) and react-native (>=0.72) are peer dependencies. The optional @react-native-async-storage/async-storage and expo-* modules are used when present but never required.

Usage

import { TillPulse } from '@tillstack/react-native'

await TillPulse.init({
  dsn: 'https://<key>@ingest.tilldev.dev/<project-id>',
  release: '1.0.0',
  environment: 'production',
  maxDailyDataKB: 2048, // optional daily cap; errors are always sent
})

// Unhandled errors are captured automatically. Handled ones:
try {
  risky()
} catch (err) {
  TillPulse.captureError(err)
}

TillPulse.setUser({ id: hashedUserId })
TillPulse.addBreadcrumb({ type: 'custom', category: 'checkout', message: 'Opened checkout' })

await TillPulse.withTransaction({ name: 'checkout', op: 'flow' }, async (tx) => {
  const span = tx.startSpan({ op: 'http.client', description: 'POST /charge' })
  await charge()
  span.finish()
})

Native crash capture

Native crashes, OOM/force-quit, cold-start timing, frame jank and root/jailbreak detection require the native module to be linked:

• Bare React Native: cd ios && pod install, then rebuild.
• Expo: add the config plugin and rebuild a development build — native capture does not work in Expo Go.

{
  "expo": {
    "plugins": ["@tillstack/react-native"]
  }
}

On iOS the crash reporter catches signals, Mach exceptions and uncaught Objective-C exceptions, and reports the main thread stalling for 2 s (AppHangWarning) or 5 s (AppHang). Frames arrive as addresses; upload your dSYMs for each release and TillPulse resolves them to function, file and line:

tilldev pulse dsym upload <project> --release 1.4.0 --file ios/build/MyApp.xcarchive

Upload the JavaScript source map too (tilldev pulse sourcemaps upload) so JS frames read as your source.

Offline queue

With @react-native-async-storage/async-storage installed, events captured offline are stored until they are sent, for up to 7 days. The stored queue is encrypted by the native module: AES-256-GCM under a data key wrapped by an Android Keystore key (StrongBox when present) on Android, and AES-256 with HMAC-SHA256 under a keychain key that never syncs or leaves the device on iOS. The key never reaches JavaScript, and a tampered queue is discarded. Without the native module (Expo Go) events stay in memory and are never written in the clear.

Docs

Full documentation: https://tilldev.dev/docs/tillpulse/sdk/react-native

License

Apache-2.0