Skip to main content

Migrate from react-native-exception-handler

If your app already uses react-native-exception-handler, this guide walks through the switch to react-native-global-exception-handler with minimal churn. The main changes are the package import, the native handler options shape, and the release-build checks around JavaScript and native crash flows. In most apps, the migration is small, but it is still worth verifying both debug and release behavior before shipping.

Why move to react-native-global-exception-handler​

  • clearer native handler configuration through an options object
  • first-class TypeScript support
  • built-in simulateNativeCrash utility for QA and release verification
  • updated docs for iOS, Android, and new architecture projects

If you want a high-level package comparison first, read react-native-exception-handler vs react-native-global-exception-handler.

What stays the same​

  • You still register a global JavaScript exception handler.
  • You still register a native exception handler for crash reporting.
  • Existing ideas like restart flows, chaining previous handlers, and analytics forwarding still apply.

Main API difference​

The largest migration change is the native handler signature.

// Older style
setNativeExceptionHandler(handler, true, false);

// Recommended current style
setNativeExceptionHandler(handler, {
  forceAppToQuit: true,
  callPreviouslyDefinedHandler: false,
});

Migration steps​

1. Replace the dependency​

npm uninstall react-native-exception-handler
npm install react-native-global-exception-handler
cd ios && pod install

2. Update imports​

// Before
import { setJSExceptionHandler } from 'react-native-exception-handler';

// After
import { setJSExceptionHandler } from 'react-native-global-exception-handler';

3. Move native handler booleans into the options object​

// Before
setNativeExceptionHandler(handler, true, false);

// After
setNativeExceptionHandler(handler, {
  forceAppToQuit: true,
  callPreviouslyDefinedHandler: false,
});

If your old setup depended on chaining another native handler, keep that behavior explicitly:

setNativeExceptionHandler(handler, {
  forceAppToQuit: true,
  callPreviouslyDefinedHandler: true,
});

4. Re-test release behavior​

After the code change, validate:

  1. JavaScript exception handling
  2. native crash handling in release builds
  3. analytics forwarding to Sentry or Crashlytics
  4. any custom restart or recovery flow

Use Simulate Native Crash in React Native for the native-crash part of that test.

FAQ​

Do I need to rewrite my JavaScript exception handler?​

No. The core JS handler pattern stays the same.

Is the old positional native API removed?​

No. It is still supported for backward compatibility, but new code should use the object form.

What if I already chain another handler?​

Use callPreviouslyDefinedHandler: true and review the full signature in the API Reference.

Credits​

This library builds on the ideas popularized by the original project:

The migration path exists because that earlier work made the JS/global-handler model familiar to many React Native teams.

Next actions​