Skip to main content

AI Agents

This page mirrors the canonical machine-readable guide at /llms.txt. Use it when you want the same guidance in a format that is easier to review in the docs site.

What this package does​

A React Native library for JavaScript and native exception handling, graceful fallback flows, and crash-reporting integrations. It is designed for apps that need one place to register handlers, validate release-mode crash behavior, and forward failures to Sentry, Crashlytics, or a custom backend.

Read these first​

  • Getting Started: Use this first if you are adding the package to an app for the first time.
  • Installation: Confirms iOS pods, Android autolinking, and native module registration.
  • Basic Usage: Shows the minimum JavaScript and native handler setup most apps need.
  • Native Crash Handling: Explains iOS and Android platform limits before release testing.
  • API Reference: Covers signatures, defaults, and option behavior.
  • Troubleshooting: Use when pods, native linking, or crash capture do not behave as expected.

Typical tasks​

Public API at a glance​

setJSExceptionHandler(customHandler, allowedInDevMode)

Registers the global JavaScript exception handler.

  • Use for uncaught JavaScript exceptions before the app exits.
  • allowedInDevMode lets you opt into handler behavior during development.

getJSExceptionHandler()

Returns the currently registered JavaScript exception handler.

  • Useful when you need to preserve or chain an existing JS handler.

setNativeExceptionHandler(customErrorHandler, options)

Registers the native exception handler.

  • Prefer the options-object signature over the older positional form.
  • Keep native crash work minimal and validate behavior in release builds.

getNativeExceptionHandler()

Returns the currently registered native exception handler.

  • Use when you need to preserve or inspect an existing native handler.

simulateNativeCrash(crashType)

Simulates a native crash for QA and release validation.

  • Do not expose this through end-user flows.
  • Use a controlled test environment when validating destructive crash types.

Core options​

forceAppToQuit (default: true)

  • Primarily an Android-focused option.
  • Use with care if you are attempting advanced recovery flows.

callPreviouslyDefinedHandler (default: false)

  • Use when another SDK or native layer already installed a handler.
  • Relevant for Sentry, Crashlytics, or custom native crash pipelines.

Common mistakes agents make​

  • Native crash handling is more limited than JavaScript exception handling
  • Debug behavior is not a reliable proxy for release behavior
  • iOS and Android native crash flows differ materially
  • Some integrations require chaining a previously defined native handler
  • simulateNativeCrash is for QA and release validation, not end-user flows

Platform caveats​

Shared caveats​

  • JavaScript exceptions and native crashes are not interchangeable.
  • Release builds are the only reliable way to validate native crash behavior.

iOS​

  • Native crash recovery is more limited on iOS.
  • Do not assume a normal React Native UI flow is still safe after a fatal native crash.

Android​

  • Android offers more flexibility for restart-oriented recovery flows.
  • forceAppToQuit changes how advanced Android recovery attempts behave.

Testing and release-mode validation​

  • Use simulateNativeCrash for release validation, not as a production feature.
  • Test JavaScript handling and native crash handling separately.
  • Verify provider integrations end-to-end in the same environment you plan to ship.
  • If native results differ from expectations, compare debug and release behavior before changing handler logic.

Migration notes​

Example entry points​