react-native-global-exception-handler


A modern React Native library for global error handling (JavaScript + native) with TurboModules support and cross-platform compatibility.

> 🎬 See live demos of iOS and Android crash handling in action!

Key Features

- 🔥 Modern Architecture: Built with TurboModules for React Native 0.68+
- 📱 Cross-Platform: Full iOS and Android support
- 🎯 Dual Exception Handling: Catches both JS and native exceptions
- 🔧 Highly Customizable: Configurable options for different platforms
- 🚀 Crash Simulation: Built-in crash testing for development
- 🎨 Custom Error UI: Platform-specific error screens with restart functionality
- ⚡ TypeScript Support: Full TypeScript definitions included

Why

In React Native apps, uncaught exceptions behave differently based on the environment:

- In DEV mode: You get a helpful Red Screen error showing the stack trace
- In production (bundled) mode: The app simply quits without any message 😱

This creates a poor user experience where users don't know:

- What went wrong
- Whether they should restart the app
- If their data was saved

This library solves this by:

1. Catching unhandled exceptions before the app crashes
2. Allowing you to show a graceful error message to users
3. Enabling error reporting to your development team
4. Providing restart capabilities for recovery

Documentation

📚 View Full Documentation

$3

- Getting Started - Installation and setup
- Usage Guide - JS exception handling
- Native Crash Handling - Platform-specific native handlers
- API Reference - Complete API documentation
- Testing & Simulation - simulateNativeCrash and testing
- Analytics Integration - Sentry, Crashlytics, custom services
- Customization - Custom error screens
- Troubleshooting - Common issues and solutions
- Migration Guide - From react-native-exception-handler

Installation

``sh
npm install react-native-global-exception-handler


or


yarn add react-native-global-exception-handler
`

> Requires React Native 0.68+ (TurboModules & auto-linking)

$3

Works with both:

- Legacy Architecture (Old Architecture)
- New Architecture (TurboModules + Fabric)

No additional configuration needed; the correct bindings are auto-selected at build time.

Quick Start

$3

`js
import { setJSExceptionHandler } from 'react-native-global-exception-handler';

// Basic setup
setJSExceptionHandler((error, isFatal) => {
console.log('JS Exception:', error);

if (isFatal) {
// Handle fatal errors - maybe show restart dialog
} else {
// Handle non-fatal errors - maybe just log them
}
});

// Advanced setup with dev mode control
setJSExceptionHandler(
(error, isFatal) => {
// Your error handler
},
true // allowedInDevMode: true = enable in dev (shows instead of RedBox)
);
`

$3

`js
import { setNativeExceptionHandler } from 'react-native-global-exception-handler';

// Basic setup with default options
setNativeExceptionHandler((errorString) => {
console.log('Native Exception:', errorString);
// Send to crash reporting service
});

// Advanced setup with platform-specific options
setNativeExceptionHandler(
(errorString) => {
console.log('Native Exception:', errorString);
},
{
forceAppToQuit: true, // Android: Force app to quit after error (default: true)
callPreviouslyDefinedHandler: false // Call previous exception handler (default: false)
}
);
``

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

Credits & Attribution

This project is inspired by the original work in react-native-exception-handler created by its original authors and community of contributors. Many foundational ideas (global JS/native handler approach, restart patterns, native popup customization) originated there.

License

MIT

---

Made with ❤️ for the React Native community