expo-exception-handler

A comprehensive exception handler for Expo applications, ported from react-native-exception-handler. This module allows you to handle both JavaScript and native exceptions in your Expo apps.

Installation

expo install expo-exception-handler

Usage

JavaScript Exception Handling

import { setJSExceptionHandler } from "expo-exception-handler";

// Set up a global JS error handler
setJSExceptionHandler((error, isFatal) => {
  // This is your custom JS error handler
  // You can log to a remote server, show a custom UI, etc.
  console.log("Caught JS Exception:", error);
  console.log("Is fatal:", isFatal);

  // You can show a custom error screen here
  // For example:
  Alert.alert(
    "Unexpected error occurred",
    "We encountered an unexpected error. Please restart the app.",
    [
      {
        text: "OK",
        onPress: () => {
          // Optional: You can force quit the app on fatal errors
          if (isFatal) {
            RNRestart.Restart();
          }
        },
      },
    ],
    { cancelable: false }
  );
}, true);

Native Exception Handling

import { setNativeExceptionHandler } from "expo-exception-handler";

// Set up a native exception handler
setNativeExceptionHandler(
  (errorString) => {
    // This is your custom native error handler
    // You can log to a remote server, save to AsyncStorage, etc.
    console.log("Caught Native Exception:", errorString);

    // Note: This callback is executed in a context where the JS runtime might be
    // unstable. You should not call any JS functions from here.
    // It's best to just log the error or save it for later reporting.
  },
  false, // Don't force quit the app
  true // Execute in the global context
);

Advanced Options

import {
  setJSExceptionHandlerWithOptions,
  setNativeExceptionHandlerWithOptions,
  getDeviceInfo,
} from "expo-exception-handler";

// Set up JS exception handler with options
setJSExceptionHandlerWithOptions({
  onError: (error, isFatal) => {
    // Your custom error handler
  },
  catchErrorsNotCaughtByReact: true, // Allow handling errors not caught by React
});

// Set up native exception handler with options
setNativeExceptionHandlerWithOptions({
  onError: (errorString) => {
    // Your custom error handler
  },
  forceQuitOnError: false, // Don't force quit the app on error
});

// Get device information for error reporting
async function logErrorWithDeviceInfo(error) {
  const deviceInfo = await getDeviceInfo();
  console.log("Error occurred on:", deviceInfo);
  console.log("Error:", error);

  // Send to your error reporting service
  // await sendToErrorService({ error, deviceInfo });
}

API Reference

JavaScript Exception Handling

setJSExceptionHandler(handler, allowedInDevMode)

Sets a global handler that will be called when a JavaScript exception occurs.

• handler: (error: Error, isFatal: boolean) => void - A function that will be called with the error and a boolean indicating if the error is fatal.
• allowedInDevMode: boolean - Whether to call the handler in development mode. Default is false.

setJSExceptionHandlerWithOptions(options)

Sets a global handler with additional options.

• options: JSExceptionHandlerOptions
  • onError: (error: Error, isFatal: boolean) => void - The error handler function.
  • catchErrorsNotCaughtByReact: boolean - Whether to catch errors not caught by React. Default is false.

Native Exception Handling

setNativeExceptionHandler(handler, forceQuitOnError, executeInContext)

Sets a handler for native exceptions.

• handler: (errorString: string) => void - A function that will be called with the error string.
• forceQuitOnError: boolean - Whether to force quit the app after handling the error. Default is false.
• executeInContext: boolean - Whether to execute the handler in the current context. Default is false.

setNativeExceptionHandlerWithOptions(options)

Sets a native exception handler with additional options.

• options: NativeExceptionHandlerOptions
  • onError: (errorString: string) => void - The error handler function.
  • forceQuitOnError: boolean - Whether to force quit the app after handling the error. Default is false.

Utility Functions

getDeviceInfo()

Returns device information that can be useful for error reporting.

Returns: Promise<object> - An object containing device information.

License

MIT