react-native-exception-handler
A react native module that lets you to register a global error handler that can capture fatal/non fatal uncaught exceptions. The module helps prevent abrupt crashing of RN Apps without a graceful message to the user.
In the current scenario:
In DEV mode , you get a RED Screen error pointing your errors.In Bundled mode , the app just quits without any prompt !?
To tackle this we register a global error handler that could be used to for example:
- Send bug reports to dev team when the app crashes
- Show a creative dialog saying the user should restart the application
UPDATE - V2:
V2 of this module now supports catching Unhandled Native Exceptions also along with the JS Exceptions ✌??
There are NO breaking changes. So its safe to upgrade from v1 to v2. So there is no reason not to ?.
Example repo can be found here:
*https://github.com/master-atul/react-native-exception-handler-example *
Screens
Without any error handling
In DEV MODE
In BUNDLED MODE
With react-native-exception-handler in BUNDLED MODE
Installation:
yarn add react-native-exception-handler
or
npm i react-native-exception-handler --save
Mostly automatic installation
react-native link react-native-exception-handler
Manual installation
iOS
- In XCode, in the project navigator, right click
Libraries➜Add Files to [your project's name] - Go to
node_modules➜react-native-exception-handlerand addReactNativeExceptionHandler.xcodeproj - In XCode, in the project navigator, select your project. Add
libReactNativeExceptionHandler.ato your project'sBuild Phases➜Link Binary With Libraries - Run your project (
Cmd+R)<
Android
- Open up
android/app/src/main/java/[...]/MainApplication.java
- Add
import com.masteratul.exceptionhandler.ReactNativeExceptionHandlerPackage;to the imports at the top of the file - Add
new ReactNativeExceptionHandlerPackage()to the list returned by thegetPackages()method
- Append the following lines to
android/settings.gradle:include ':react-native-exception-handler' project(':react-native-exception-handler').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-exception-handler/android') - Insert the following lines inside the dependencies block in
android/app/build.gradle:compile project(':react-native-exception-handler')
PLEASE READ BEFORE GOING TO USAGE SECTION
Lets introduce you to the type of errors in a RN app.
-
Errors produced by your Javascript code (includes all your react code). We will refer to these errors as JS_Exceptions going forward.
-
Errors produced by Native Modules. We will refer to these as Native_Exceptions going forward.
Unhandled exceptions leave the app in a critical state.
In case of JS_Exceptions you can catch these unhandled exceptions and perform tasks like show alerts or popups, do cleanup or even hit an API to inform the dev teams before closing the app.
In case of Native_Exceptions it becomes much worse. While you can catch these unhandled exceptions and perform tasks like cleanup or logout or even hit an API to inform the dev teams before closing the app,
you CANNOT show a JS alert box or do any UI stuff via JS code. This has to be done via the native methods provided by this module in the repective NATIVE codebase for iOS and android. The module does provide default handlers though :P. So you will get default popups incase of errors. Obviously you can customise them. See CUSTOMIZATION section.
Usage
To catch JS_Exceptions
import {setJSExceptionHandler, getJSExceptionHandler} from 'react-native-exception-handler';
.
.
// registering the error handler (maybe u can do this in the index.android.js or index.ios.js)
setJSExceptionHandler((error, isFatal) => {
// This is your custom global error handler
// You do stuff like show an error dialog
// or hit google analytics to track crashes
// or hit a custom api to inform the dev team.
});
// getJSExceptionHandler gives the currently set JS exception handler
const currentHandler = getJSExceptionHandler();
To catch Native_Exceptions
import {setNativeExceptionHandler} from 'react-native-exception-handler';
setNativeExceptionHandler((exceptionString) => {
// This is your custom global error handler
// You do stuff likehit google analytics to track crashes.
// or hit a custom api to inform the dev team.
//NOTE: alert or showing any UI change via JS
//WILL NOT WORK in case of NATIVE ERRORS.
});
It is recommended you set both the handlers.
See the examples to know more
CUSTOMIZATION
Customizing setJSExceptionHandler.
In case of setJSExceptionHandler you can do everything that is possible. Hence there is not much to customize here.
const errorHandler = (error, isFatal) => {
// This is your custom global error handler
// You do stuff like show an error dialog
// or hit google analytics to track crashes
// or hit a custom api to inform the dev team.
})
//Second argument is a boolean with a default value of false if unspecified.
//If set to true the handler to be called in place of RED screen
//in development mode also.
setJSExceptionHandler(errorHandler, true);
Customizing setNativeExceptionHandler
By default whenever a Native_Exceptions occurs if you have used setNativeExceptionHandler, along with the callback specified you would see a popup (this is the default native handler set by this module).
In Android and iOS you will see something like
Modifying Android Native Exception handler UI (NATIVE CODE HAS TO BE WRITTEN) recommended that you do this in android studio
- Create an Empty Activity in the
android/app/src/main/java/[...]/. For example lets say CustomErrorDialog.java - Customize your activity to look and behave however you need it to be.
- In the
android/app/src/main/java/[...]/MainApplication.java
import com.masteratul.exceptionhandler.ReactNativeExceptionHandlerModule;
import <yourpackage>.YourCustomActivity; //This is your CustomErrorDialog.java
...
...
...
public class MainApplication extends Application implements ReactApplication {
...
...
@Override
public void onCreate() {
....
....
....
ReactNativeExceptionHandlerModule.replaceErrorScreenActivityClass(YourCustomActivity.class); //This will replace the native error handler popup with your own custom activity.
}
Modifying iOS Native Exception handler UI (NATIVE CODE HAS TO BE WRITTEN) recommended that you do this in XCode
Unlike Android, in the case of iOS, there is no way to restart the app if it has crashed. Also, during a Native_Exceptions the UI becomes quite unstable since the exception occured on the main UI thread. Hence, none of the click or press handlers would work either.
Keeping in mind of these, at the most we can just show the user a dialog and inform the user to reopen the app.
If you noticed the default native exception popup does exactly that. To customize the UI for the popup.
- In XCode, open the file
AppDelegate.m
#import "AppDelegate.h"
#import <React/RCTBundleURLProvider.h>
#import <React/RCTRootView.h>
//Add the header file
#import "ReactNativeExceptionHandler.h"
...
...
@implementation AppDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
...
...
[ReactNativeExceptionHandler replaceNativeExceptionHandlerBlock:^(NSException *exception, NSString *readeableException){
// THE CODE YOU WRITE HERE WILL REPLACE THE EXISTING NATIVE POPUP THAT COMES WITH THIS MODULE.
//We create an alert box
UIAlertController* alert = [UIAlertController
alertControllerWithTitle:@"Critical error occurred"
message: [NSString stringWithFormat:@"%@\n%@",
@"Apologies..The app will close now \nPlease restart the app\n",
readeableException]
preferredStyle:UIAlertControllerStyleAlert];
// We show the alert box using the rootViewController
[rootViewController presentViewController:alert animated:YES completion:nil];
// THIS IS THE IMPORTANT PART
// By default when an exception is raised we will show an alert box as per our code.
// But since our buttons wont work because our click handlers wont work.
// to close the app or to remove the UI lockup on exception.
// we need to call this method
// [ReactNativeExceptionHandler releaseExceptionHold]; // to release the lock and let the app crash.
// Hence we set a timer of 4 secs and then call the method releaseExceptionHold to quit the app after
// 4 secs of showing the popup
[NSTimer scheduledTimerWithTimeInterval:4.0
target:[ReactNativeExceptionHandler class]
selector:@selector(releaseExceptionHold)
userInfo:nil
repeats:NO];
// or you can call
// [ReactNativeExceptionHandler releaseExceptionHold]; when you are done to release the UI lock.
}];
...
...
...
return YES;
}
@end
What is this [ReactNativeExceptionHandler releaseExceptionHold];?
In case of iOS we lock the UI thread after we show our popup to prevent the app from closing.
Hence once we are done showing the popup we need to close our app after some time.
But since our buttons wont work as our click handlers wont work (explained before).
To close the app or to remove the UI lockup on exception, we need to call this method
[ReactNativeExceptionHandler releaseExceptionHold];
Hence we set a timer of 4 secs and then call the method releaseExceptionHold to quit the app after
4 secs of showing the popup
[NSTimer scheduledTimerWithTimeInterval:4.0
target:[ReactNativeExceptionHandler class]
selector:@selector(releaseExceptionHold)
userInfo:nil
repeats:NO];
Examples
Restart on error example
This example shows how to use this module show a graceful bug dialog to the user on crash and restart the app when the user presses ok !
import {Alert} from 'react-native';
import RNRestart from 'react-native-restart';
import {setJSExceptionHandler} from 'react-native-exception-handler';
const errorHandler = (e, isFatal) => {
if (isFatal) {
Alert.alert(
'Unexpected error occurred',
`
Error: ${(isFatal) ? 'Fatal:' : ''} ${e.name} ${e.message}
We will need to restart the app.
`,
[{
text: 'Restart',
onPress: () => {
RNRestart.Restart();
}
}]
);
} else {
console.log(e); // So that we can see it in the ADB logs in case of Android if needed
}
};
setJSExceptionHandler(errorHandler);
setNativeExceptionHandler((errorString) => {
//You can do something like call an api to report to dev team here
...
...
// When you call setNativeExceptionHandler, react-native-exception-handler sets a
// Native Exception Handler popup which supports restart on error in case of android.
// In case of iOS, it is not possible to restart the app programmatically, so we just show an error popup and close the app.
// To customize the popup screen take a look at CUSTOMIZATION section.
});
Bug Capture to dev team example
This example shows how to use this module to send global errors to the dev team and show a graceful bug dialog to the user on crash !
import {Alert} from 'react-native';
import {BackAndroid} from 'react-native';
import {setJSExceptionHandler} from 'react-native-exception-handler';
const reporter = (error) => {
// Logic for reporting to devs
// Example : Log issues to github issues using github apis.
console.log(error); // sample
};
const errorHandler = (e, isFatal) => {
if (isFatal) {
reporter(e);
Alert.alert(
'Unexpected error occurred',
`
Error: ${(isFatal) ? 'Fatal:' : ''} ${e.name} ${e.message}
We have reported this to our team ! Please close the app and start again!
`,
[{
text: 'Close',
onPress: () => {
BackAndroid.exitApp();
}
}]
);
} else {
console.log(e); // So that we can see it in the ADB logs in case of Android if needed
}
};
setJSExceptionHandler(errorHandler);
setNativeExceptionHandler((errorString) => {
//You can do something like call an api to report to dev team here
//example
// fetch('http://<YOUR API TO REPORT TO DEV TEAM>?error='+errorString);
//
});
More Examples can be found in the examples folder
- Preserving old handler (thanks to zeh)
