Early accessBy invitation, and the SDKs aren't published yet.Ask for an invitation
Skip to Content
Docs

React Native

Structured logs, JavaScript errors and crashes from your React Native app, over the Swift and Android SDKs.

iOS and Android apps, over the native SDKs

The React Native SDK is a thin TurboModule over the Swift and Android SDKs. The native SDKs keep the queue on disk, send in batches, retry, keep sessions and report native crashes. This package adds what only JavaScript sees: uncaught errors, unhandled promise rejections, React render errors and React Navigation screens.

It needs React Native 0.80 or later with the New Architecture, and React 19. Apps run on iOS 16 or later and Android 7.0 (API 24) or later.

Internal preview: this package isn't published yet. Until it is, @lyrelog/react-native isn't on npm, and the native SDKs it builds on aren't published either.

Install

pnpm add @lyrelog/react-native
cd ios && pod install

On iOS the pod brings the Lyrelog Swift package through Swift Package Manager. Set your app's deployment target (and the platform :ios line in the Podfile) to 16.0 or later. On Android, Gradle fetches com.lyrelog:lyrelog-android from Maven Central, which adds the INTERNET permission.

Start

Start once, as early as possible, in index.js before AppRegistry. A second call keeps the first configuration. Events logged before init are ignored, but setUser and setConsent called before init are kept and applied when it runs.

import { AppRegistry } from "react-native";
import { Lyrelog } from "@lyrelog/react-native";
import App from "./src/App";

Lyrelog.init({
  apiKey: "lyr_ing_...",   // ingest-only: it can append events, never read them
});

AppRegistry.registerComponent("main", () => App);

Events go to https://ingest.lyrelog.com. Pass endpoint only to send them somewhere else. It must be https; plain http works only for localhost, 127.0.0.1 or ::1 (the iOS simulator), and on the Android emulator for 10.0.2.2.

Nothing in the SDK throws into your app. In a development build, a missing key or a missing native module (the app wasn't rebuilt after installing) is reported once with console.warn.

Log events

One function per level: trace, debug, info, notice, warning, error, critical, or log(level, message, options).

Lyrelog.info("checkout_done", { attrs: { items: 3, latency_ms: ms } });
Lyrelog.error("payment_declined", {
  category: "checkout",
  attrs: { code: 51 },
  payload: { response },
});

Attributes are small fields to filter and chart by: strings, numbers, booleans, null, arrays and nested objects up to 4 levels. The payload is any JSON, for the detail you only read when you open one event. minimumLevel (default debug) drops lower levels before they cross to native code.

Loggers for each area

A logger stamps its category on every event. It has every level, plus log and captureException.

const sync = Lyrelog.logger("sync");
sync.warning("sync_conflict", { attrs: { records: 2 } });

Users

Lyrelog.setUser(playerId);   // attached to every following event
Lyrelog.setUser(null);       // on sign-out

Lyrelog.sessionId gives the current session id, for example to show in a support screen. The user id isn't saved between launches: call setUser again on each launch.

Screens

With React Navigation, spread trackNavigation on the container:

import { NavigationContainer, createNavigationContainerRef } from "@react-navigation/native";
import { trackNavigation } from "@lyrelog/react-native";

const navigationRef = createNavigationContainerRef();

export default function App() {
  return (
    <NavigationContainer ref={navigationRef} {...trackNavigation(navigationRef)}>
      {/* your navigators */}
    </NavigationContainer>
  );
}

Each screen shown logs screen_viewed (area navigation) with screen, previous_screen and seconds_on_previous, and every following event is tagged with a screen attribute. The name is the route's; pass name: (route) => ... to choose another, or return undefined to skip a route. Your own onReady and onStateChange go in the options and run after Lyrelog's.

Without React Navigation, call Lyrelog.screen("Settings"), or useLyrelogScreen("Settings") in the screen's component. Calling screen again with the same name logs nothing. Turn the tagging off with attachScreen: false.

Errors you catch

try {
  await store.purchase(product);
} catch (error) {
  Lyrelog.captureException(error, { category: "store" });
}

It sends the exception event every SDK sends: level error, the attributes error_type and error_message, and a payload with the name, message, stack and up to 3 causes (error.cause). attrs adds your own; level changes the level. Anything can be thrown in JavaScript: a string or an object is recorded too.

Stacks are as Hermes reports them. In a release build they point into the bundle: keep the build's source map to read them.

Errors nobody caught

With captureErrors (on by default), the SDK hooks into React Native's error handling:

What happensEventLevel, areamechanism
A fatal JavaScript error, such as a throw in a timer or an event handlerapp_crashedcritical, diagnosticsjs_fatal
A render error no error boundary caughtapp_crashedcritical, diagnosticsreact_render
A non-fatal error reported to ErrorUtilsexception, handled: falseerrorjs_error
An unhandled promise rejectionexception, handled: falseerrorunhandled_rejection

A fatal error is written to disk before the app goes, waiting up to 1.5 seconds, and is sent then if it can be, otherwise on the next launch. It is app_crashed in the diagnostics area, like the native crash reports, so JavaScript and native crashes sit together in the dashboard.

Each error is recorded once. Uncaught errors that aren't fatal are capped at 10 a minute, and the same one at most once every 10 seconds; Lyrelog.skippedErrors counts what was left out. The handlers that were there before still run: the red box and LogBox in development, the crash in release.

Error boundaries

import { LyrelogErrorBoundary } from "@lyrelog/react-native";

<LyrelogErrorBoundary
  category="feed"
  fallback={({ error, reset }) => <Retry onPress={reset} />}
>
  <Feed />
</LyrelogErrorBoundary>

A render error below it is recorded as exception with mechanism: error_boundary and React's component stack (component_stack in the payload), and fallback is shown instead. onError is called after it is recorded. Without a fallback it renders nothing after an error.

Native crashes

These are the native SDKs' (captureCrashes, on by default), sent on the next launch in the diagnostics area: uncaught JVM exceptions on Android as app_crashed; on iOS MetricKit's reports, crashes as app_crashed and hangs as app_hung. See Android crashes and Swift crashes and hangs.

On Android, a fatal JavaScript error ends the app with a Java exception. Once the JavaScript app_crashed is on disk, that exception skips the Android SDK's recorder, so the same crash isn't reported twice.

Environments and platform

The environment is the native SDK's: on iOS development in debug builds, testflight on TestFlight, production otherwise; on Android development when the app is debuggable, production otherwise. Your own debug builds send development, while the dashboard opens on production: pick development in the top bar to see them.

The platform is ios or android. Override either:

Lyrelog.init({
  apiKey: key,
  environment: isBeta ? "beta" : undefined,   // undefined = detected
});

Events name this package and the native SDK under it (sdk is lyrelog-react-native/0.1.0 lyrelog-swift/0.1.0 or lyrelog-react-native/0.1.0 lyrelog-android/0.1.0).

Lyrelog.init({ apiKey: key, consent: "pending" });
// later, when the person chooses:
Lyrelog.setConsent("granted");   // sends, including what was kept while pending
Lyrelog.setConsent("denied");    // deletes everything and stops recording

pending keeps events on the device without sending them. Nothing is uploaded unless consent is granted. Consent isn't saved between launches: store the person's choice yourself (for example with AsyncStorage) and pass it to init each time.

Attestation

attest (on by default) proves the app with App Attest on iOS and Key Attestation on Android, so its events are stored as verified. See Verified events.

Options

OptionDefaultWhat
apiKeyThe project's ingest key, lyr_ing_...
endpointhttps://ingest.lyrelog.comWhere events go
consentgrantedgranted, pending or denied
environmentdetectedAny name
platformios / androidWhich part of the product sends
minimumLeveldebugLower levels are dropped
flushIntervalMs15000How often queued events are sent in the foreground
sessionTimeoutMs30 minutesA new session after this long without an event
maxDiskBytes20 MBWhat may wait on the device; the oldest go first
redactKeysDEFAULT_REDACT_KEYSAttribute and payload keys whose values are replaced. Your list replaces the defaults; [] turns it off
captureErrorstrueJavaScript errors nobody caught
captureCrashestrueNative crashes
attachScreentrueThe screen attribute on every event
attesttrueApp Attest and Key Attestation
mirrorToNativeLogfalseAlso print every event to the Xcode console or logcat

Flush and stop

Going to the background already sends, so you rarely need to.

await Lyrelog.flush();   // write everything to disk and try to send now
await Lyrelog.close();   // send what's queued (up to 2 seconds), then stop

After close, init can be called again.