Debug a crash

Read the error in JavaScript

terminal

Error: The config is empty
    at parseConfig (/Users/you/app/src/config.lucent.ts:6)
    at App (App.tsx:12)

An error made in Lucent, with error() or new Error, reaches JavaScript with its first stack frame at the .lucent.ts line that made it.

Read the logs

• iOS: Console.app or Xcode's console, filtered on [Lucent]. console.log in a module writes there.
• Android: adb logcat -s Lucent.
• An error nothing catches, such as one thrown in an SDK callback, is logged as [lucent] uncaught exception in ….

Symbolicate a native crash

The C++ carries #line directives, so its debug information points at your .lucent.ts files. With the app's dSYM on iOS, or its unstripped .so on Android, a crash report names the module's file and line. Xcode and Android Studio also step through .lucent.ts lines.

Inspect a running app

In a debug build, ask React Native's DevTools console:

DevTools console

await __lucentDebug.snapshot();

It counts what Lucent owns and gives each mounted component's native view tree, with frames. A count that grows each time you reopen a screen is a leak. In a trace, each effect's runs are effect events at their .lucent.ts line.

Check the setup

terminal

npx lucent doctor

Lucent: the native module is not linked means the app was built without the native package: run lucent build, then pod install, and rebuild. module "x" is not in the native build means the app is older than the module: rebuild it.

Each proxy checks that the app's native code was built from the same sources as the JavaScript. When it wasn't, the error says what to do: rebuild and reinstall the app (compile-native), or reload JavaScript built for the installed app (reload-js). When only function bodies differ, it's a warning.

A JavaScript update, a reload or an update over the air, can't replace native code.

lucent doctor reads the app's build too, before the app runs:

• Last build: the steps the last lucent build failed at, such as an Android dependency conflict, with what each said and its log.
• Build cache: which steps ran again, and which input changed for each.
• Native targets: a platform the app has that this JavaScript was built without.
• Native build: the newest native build of the app, from Xcode or Gradle, checked as the app checks it. A module with another API would be refused, so doctor fails; other sources with the same APIs get a warning.