@koderlabs/tasks-sdk-rn-native

Runtime: React Native on iOS / Android via an Expo prebuild (EAS Build or expo prebuild). Will not work in Expo Go (managed runtime cannot load native code). Not a JS-only package. Companion to @koderlabs/tasks-sdk-rn.

Captures native crashes that escape the JS runtime — segfaults, ObjC NSExceptions, Android Throwables — plus an opt-in Android ANR watchdog. Reports are written to disk by the native side and drained on next launch by @koderlabs/tasks-sdk-rn (captureNativeCrash: true).

What it captures

iOS (PLCrashReporter bundled as a Pod):

• Mach exceptions
• BSD signals (SIGSEGV, SIGBUS, SIGABRT, SIGFPE, SIGILL, SIGPIPE, SIGTRAP)
• ObjC NSExceptions

Android (JNI signal handler — libtasks_native_crash.so):

• SIGSEGV, SIGBUS, SIGABRT, SIGFPE, SIGILL with backtrace addresses
• Optional ANR watchdog thread (opt-in; OS-level ANR detection is usually enough)

Install

npm install @koderlabs/tasks-sdk @koderlabs/tasks-sdk-rn @koderlabs/tasks-sdk-rn-native
# or
pnpm add @koderlabs/tasks-sdk @koderlabs/tasks-sdk-rn @koderlabs/tasks-sdk-rn-native
# or
yarn add @koderlabs/tasks-sdk @koderlabs/tasks-sdk-rn @koderlabs/tasks-sdk-rn-native

Then register the Expo config plugin in app.json / app.config.ts:

{
  "expo": {
    "plugins": ["@koderlabs/tasks-sdk-rn-native"]
  }
}

Prebuild:

npx expo prebuild --clean
# or: eas build

Usage

// App.tsx — early bootstrap, before any user interaction
import { init } from '@koderlabs/tasks-sdk-rn';
import { enableNativeCapture } from '@koderlabs/tasks-sdk-rn-native';

init({
  projectId: 'IT-MOBILE',
  accessKey: 'sk_live_…',
  captureNativeCrash: true,            // sdk-rn drains the report on next launch
  onNativeCrashError: console.warn,
});

await enableNativeCapture({
  enableAnrWatchdog: false,            // default off
  anrThresholdMs: 5000,
  onError: (err) => console.warn('[IT native]', err.stage, err.message),
});

That's it — register early, then the package operates passively. When a native crash happens, the report is written to disk; on the next launch sdk-rn reads, ships, and purges it.

API

| Export | Purpose | |---|---| | enableNativeCapture(opts?) | Install signal handlers + optional ANR watchdog. Idempotent. Resolves true on success, false when the native module isn't loaded. | | getPendingNativeCrash(onError?) | Read the on-disk report from the previous launch. Returns null if none or on error. Usually called by sdk-rn. | | purgePendingNativeCrash(onError?) | Delete the on-disk report. Safe to call when nothing's there. | | generateTestNativeReport(onError?) | Write a fake report without crashing. For dev/CI verification. | | Types: EnableOptions, NativeError, NativeErrorHandler, NativeCrashReport. |

EnableOptions

| Option | Type | Default | Notes | |---|---|---|---| | enableAnrWatchdog | boolean | false | Android only. Soft watchdogs are noisy on slow devices — the OS does its own ANR detection. | | anrThresholdMs | number | 5000 | Matches OS-level Activity ANR. | | onError | (NativeError) => void | — | Surface load/runtime failures. Without it, "no crash" and "decode failed" look identical. |

NativeError.stage

'require-core' | 'require-native' | 'enable' | 'get-report' | 'purge' | 'test-report' — lets callers distinguish "native module not installed" from a genuine runtime failure that silenced crash reporting.

Caveats

• Expo Go cannot load native code. Use expo prebuild or EAS Build. The JS layer falls back to sdk-rn-only behaviour when the native module isn't present — no crash, but no native capture either.
• Symbol resolution for .so backtraces requires a CLI source-map upload step (planned follow-up — not in v1).
• Crashpad/Breakpad is not bundled. A future package may replace the custom signal handler with richer stack walks; out of scope for v1.
• Re-entrant crashes inside the signal handler are not detected.
• ANR watchdog is opt-in for a reason — slow devices, debugger pauses, and intentionally long-running JS work all trigger false positives.
• iOS uses PLCrashReporter (BSD/MIT). Make sure your Podfile.lock matches CI to avoid surprise version bumps.
• enableNativeCapture() is safe to call before authentication is established.

Suite overview

Full SDK suite map + platform availability matrix: docs/sdk/overview.md.

License

KoderLabs proprietary. See LICENSE for terms. Use of this package requires a separate signed written agreement with KoderLabs; access alone confers no rights.

Licensing inquiries: [email protected]