@koderlabs/tasks-sdk-rn

Runtime: React Native 0.72+ with Hermes or JSC. New Architecture compatible. Expo SDK 50+ recommended. Browser DOM is not supported — use @koderlabs/tasks-sdk-web-errors / @koderlabs/tasks-sdk-web-network instead.

React Native client for InstantTasks. Wraps the core SDK (@koderlabs/tasks-sdk) with mobile-specific instrumentation:

• Global JS error capture via ErrorUtils.setGlobalHandler.
• Unhandled promise rejections (Hermes enablePromiseRejectionTracker, JSC fallback).
• Console-as-breadcrumb capture (console.error / warn).
• fetch() network breadcrumbs (no bodies — PII guard).
• AppState foreground/background transitions.
• React Navigation / Expo Router transition breadcrumbs.
• Native-crash recovery — drains the file written by the previous launch when a native iOS NSException / Android Throwable killed the app (companion package: @koderlabs/tasks-sdk-rn-native).

Install

npm install @koderlabs/tasks-sdk @koderlabs/tasks-sdk-rn
# optional native-crash capture:
npm install @koderlabs/tasks-sdk-rn-native
# optional Expo file system (for crash recovery):
npm install expo-file-system

Using pnpm or yarn:

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

Peer: react-native. The Expo config plugin lives at @koderlabs/tasks-sdk-rn-native — register it in app.json#plugins for native crash capture.

Usage

// App.tsx or earliest possible bootstrap
import { init } from '@koderlabs/tasks-sdk-rn';

const handle = init({
  projectId: 'IT-MOBILE',
  accessKey: 'sk_live_…',
  release: '1.4.2',
  environment: 'production',
  captureGlobalErrors: true,
  captureUnhandledRejections: true,
  captureConsole: true,
  captureNetwork: true,
  captureAppState: true,
  captureNativeCrash: true,
  maxBreadcrumbs: 50,
  networkSlowThresholdMs: 2000,
  networkIncludeQueryString: false,
  onNativeCrashError: (err) => console.warn('[IT native]', err.stage, err.message),
});

// Manual capture
handle.captureException(new Error('payment failed'), { level: 'error' });

// Breadcrumbs
handle.addBreadcrumb({ category: 'user', message: 'tapped Checkout' });

// Flush before app goes to background
await handle.flush();

React Navigation integration

import { attachReactNavigation } from '@koderlabs/tasks-sdk-rn';
import { useNavigationContainerRef } from '@react-navigation/native';

const navRef = useNavigationContainerRef();
useEffect(() => attachReactNavigation(navRef, handle.buffer), []);

Expo Router

import { useExpoRouterReporter } from '@koderlabs/tasks-sdk-rn';

function RootLayout() {
  useExpoRouterReporter(handle.buffer);
  return <Slot />;
}

RnInitOptions

Extends InitOptions from @koderlabs/tasks-sdk. Mobile-specific additions:

| Option | Type | Default | Notes | |---|---|---|---| | captureGlobalErrors | boolean | true | ErrorUtils.setGlobalHandler. | | captureUnhandledRejections | boolean | true | HermesInternal where available; process.on('unhandledRejection') fallback. | | captureConsole | boolean | true | console.error / console.warn → breadcrumbs. | | captureNetwork | boolean | true | fetch() breadcrumbs. Bodies never captured. | | networkIncludeUrls | RegExp[] | — | Allowlist. | | networkExcludeUrls | RegExp[] | — | Denylist. The ingest endpoint is always skipped. | | networkSlowThresholdMs | number | 2000 | Tags requests above this as slow: true. | | networkIncludeQueryString | boolean | false | Off by default — query strings often carry tokens / emails. | | captureAppState | boolean | true | Foreground/background breadcrumbs. | | captureNativeCrash | boolean | true | Drain previous-launch native crash file. No-op when expo-file-system is absent. | | maxBreadcrumbs | number | 50 | Ring buffer. | | onNativeCrashError | (err) => void | — | Surface decode/IO failures. Without this, a failed decode is indistinguishable from "no crash". | | platformOverride | { os?, osVersion?, deviceModel?, bundleId? } | — | For tests where react-native is not loaded. |

RnClientHandle

| Method | Purpose | |---|---| | client | Underlying core Client. | | buffer | Breadcrumb buffer (also accessible via getBuffer()). | | captureException(err, { level? }) | Manual capture (fatal \| error \| warning). | | addBreadcrumb({ category, message, data?, level? }) | Manual breadcrumb. | | recordNavigation(to, { from?, params? }) | Manual navigation breadcrumb. | | flush() | Best-effort flush of queued events / spans. | | close() | Stop all auto-instrumentation. |

Globals: getClient(), getBuffer(). Re-exports: BreadcrumbBuffer, recordNavigation, attachReactNavigation, useExpoRouterReporter, types.

Caveats

• init() tears down any prior instrumentation before installing new wrappers — otherwise multiple wrappers stack on console / fetch / ErrorUtils and prior teardown functions are silently overwritten.
• Network bodies are never captured (PII risk). Only method, URL (optionally query string), status, duration.
• Native crashes require @koderlabs/tasks-sdk-rn-native to be installed and registered as an Expo plugin and a prebuild — Expo Go cannot load native code. The recovery path no-ops gracefully when the native side is absent.
• captureNativeCrash requires expo-file-system for the recovery read. Without it the option silently no-ops.
• React Navigation integration is opt-in via attachReactNavigation — there is no auto-attach.
• flush() covers spans; errors are POSTed inline so there's nothing extra to drain on the error path.
• Phase 2b will add an in-app reporter (screenshot + annotate) for RN. Until then, in-app reporting is web-only via @koderlabs/tasks-sdk-web-reporter.

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]