react-native-exception-catcher

A customizable React Native exception handler component with built-in error logging and UI fallback.

Features

• ✅ Catches both JS and Native exceptions
• ✅ Custom error UI with retry functionality
• ✅ Optional custom error content
• ✅ Error logging callback
• ✅ Device and app context collection
• ✅ TypeScript support
• ✅ Zero native dependencies for UI

Install

npm install react-native-exception-catcher react-native-exception-handler react-native-device-info react-native-restart
# or
yarn add react-native-exception-catcher react-native-exception-handler react-native-device-info react-native-restart

Peer Dependencies

This library requires:

• react-native-exception-handler - For global exception handling
• react-native-device-info - For device context
• react-native-restart - For app restart functionality

Usage

Basic Usage (Default UI)

import React from 'react';
import { ReactNativeExceptionCatcher } from 'react-native-exception-catcher';
import App from './App';

export default function Root() {
  return (
    <ReactNativeExceptionCatcher>
      <App />
    </ReactNativeExceptionCatcher>
  );
}

With Error Logging

import { ReactNativeExceptionCatcher } from 'react-native-exception-catcher';

const handleErrorLog = (payload: Record<string, unknown>) => {
  // Send to your logging service (Sentry, Firebase, etc.)
  fetch('https://your-api.com/errors', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(payload),
  });
};

export default function Root() {
  return (
    <ReactNativeExceptionCatcher onSendLog={handleErrorLog}>
      <App />
    </ReactNativeExceptionCatcher>
  );
}

With Version Tracking

<ReactNativeExceptionCatcher
  currentVersion="1.2.3"
  appVersionId={12345}
  onSendLog={handleErrorLog}
>
  <App />
</ReactNativeExceptionCatcher>

### Custom Error UI

```tsx
import { View, Text, Button } from 'react-native';
import { ReactNativeExceptionCatcher } from 'react-native-exception-catcher';

const CustomErrorScreen = () => (
  <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
    <Text>Oops! Something went wrong</Text>
    <Button title="Restart" onPress={() => RNRestart.restart()} />
  </View>
);

export default function Root() {
  return (
    <ReactNativeExceptionCatcher errorContent={<CustomErrorScreen />}>
      <App />
    </ReactNativeExceptionCatcher>
  );
}

API

Props

| Prop | Type | Required | Description | |------|------|----------|-------------| | children | ReactNode | Yes | Your app component tree | | currentVersion | string | No | App version (fallback to DeviceInfo.getVersion()) | | appVersionId | unknown | No | Your internal version ID for logging | | onSendLog | (payload: Record<string, unknown>) => void | No | Callback when an error occurs with full context | | errorContent | ReactNode | No | Custom error UI (shows default if not provided) |

Error Payload Structure

When onSendLog is called, the payload includes:

{
  device_model: string,
  message: string, // Formatted error with context
  app_version?: unknown, // If appVersionId was provided
}

The message field contains:

• Error details (name, message, stack)
• Timestamp
• Platform info
• App version and build number
• Device information (name, brand, model, OS, etc.)

Development

npm run build    # Build the library
npm run lint     # Run ESLint
npm run format   # Format with Prettier

License

ISC