@trel-to/react-native

Trel SDK for React Native: JS crashes and unhandled rejections, console logs, network spans, navigation breadcrumbs, and native crash / ANR / app-hang reporting through the Trel Android and iOS SDKs. One native transport, so a JS error and the native crash that follows share a session, user, and breadcrumb trail.

Requires a bare or prebuilt (Expo prebuild) project. Expo Go is not supported: the SDK ships a native module.

Install

npm install @trel-to/react-native
cd ios && pod install

Autolinking registers TrelNative on both platforms. The Android module depends on to.trel:trel; iOS depends on the Trel pod.

Init

import * as Trel from "@trel-to/react-native";

Trel.init({
  apiKey: "trel_sk_…",
  environment: "production",
  // release defaults to the native app version (version+build)
});

Call init as early as possible (top of index.js, before AppRegistry.registerComponent).

What is captured automatically

| Signal | How | | --- | --- | | Fatal JS errors | ErrorUtils.setGlobalHandler; reported as unhandled before the app dies, native crash is deduplicated | | Unhandled promise rejections | Hermes HermesInternal.enablePromiseRejectionTracker or the promise package tracker | | Native crashes, ANR (Android), app hangs (iOS) | Trel Android / iOS SDKs; delivered on next launch | | Console logs | console.debug/log/info/warn/error become OTLP logs (trel.source=console) and console breadcrumbs | | Network | XMLHttpRequest and fetch (including expo/fetch) become HTTP CLIENT spans with traceparent, parented to the current screen | | Sessions | Started / errored / crashed per launch; drives crash-free rate on the Releases page | | Vitals | app.start, slow/frozen frames, JS stalls over 150ms, time to initial display | | Screenshot | On by default for unhandled JS and native crashes. screenshot: { maskAllText: true } blacks out text | | Replay / profile | Off until replay.sampleRate or profilesSampleRate is above 0 |

API

Trel.captureException(err, { screen: "Checkout" });
Trel.captureMessage("Payment retried", "warn");
Trel.log("info", "cart updated", { items: 3 });
Trel.addBreadcrumb("Tapped Pay", "ui");
Trel.setUser({ id: "u_123", email: "[email protected]" });
Trel.setTag("tenant", "acme");
Trel.setContext("cart", { items: 3 });
Trel.pauseReplay();
await Trel.flush();

export default Trel.wrap(App);

Navigation

// React Navigation
const navigationRef = createNavigationContainerRef();
<NavigationContainer ref={navigationRef} onReady={() => Trel.navigation.reactNavigationIntegration(navigationRef)} />

// Expo Router (root layout)
const pathname = usePathname();
useEffect(() => Trel.navigation.expoRouterIntegration(pathname), [pathname]);

// Anything else
Trel.navigation.onRouteChange("Settings");

Route changes record navigation breadcrumbs and set the current screen. Screen spans are on unless screenSpans: false. Call Trel.navigation.timeToFullDisplay() when content is ready.

Source maps

npx react-native bundle --platform android --dev false \
  --entry-file index.js --bundle-output index.android.bundle \
  --sourcemap-output index.android.bundle.map
npx @trel-to/cli sourcemaps upload --release 1.4.0+42 ./index.android.bundle.map

Wrap Metro with withTrelDebugId from @trel-to/react-native/metro so the bundle and map share a debug id. Hermes: npx @trel-to/cli sourcemaps compose-hermes --js-map <metro.map> --hermes-map <hbc.map> --out <composed.map>. Native symbols go through npx @trel-to/cli symbols upload (--kind proguard, dsym, or ndk).

Bare iOS, in AppDelegate before the bridge starts:

[TrelBootstrap startWithApiKey:@"trel_sk_…" environment:@"production" release:nil];

Expo: add ["@trel-to/react-native", { "apiKey": "trel_sk_…" }] to plugins. The plugin starts native before JS and adds an EAS compose hook.

Options

| Option | Default | Notes | | --- | --- | --- | | environment | production | | | release | native version | version+build | | service | app / bundle id | | | console | true | { minLevel, breadcrumbs } or false | | network | true | { breadcrumbs, ignoreHosts } or false | | screenSpans | true | screen span parented to app.start | | screenshot | true | { maskAllText } blacks out text | | replay.sampleRate | 0 | JPEG replay while foregrounded | | profilesSampleRate | 0 | Hermes sampling profile for the screen | | enableAnr | true | native ANR / app-hang detection | | enableNativeNetwork | false | native OkHttp / URLSession spans (JS already covers app traffic) |

Limitations

• Expo Go is not supported (native module). Use expo prebuild / a development build.
• Obfuscated Android native frames group per release until the ProGuard mapping is uploaded.
• dSYM files are stored and listed; iOS native frames show image + address until server-side symbolication ships.

Publishing

pnpm release at the repo root bumps and publishes this package alongside @trel-to/sdk and @trel-to/cloudflare, then refreshes the public mirror at github.com/waytodev/trel-react-native (pnpm mirror:sdks react-native does the mirror alone). The native halves are published separately (Maven Central for to.trel:trel, CocoaPods trunk for Trel); see packages/sdk-android/README.md and packages/sdk-ios/README.md.