Comprehensive error handling for React Native - catches render, sync, and async errors with multi-engine support (Hermes, JSC, Web)
npm install react-native-comprehensive-error-handler> Comprehensive error handling for React Native - catches render, sync, and async errors with multi-engine support
A robust, production-ready error handling solution that catches all error types in React Native apps:
- ✅ Render errors via Error Boundaries
- ✅ Synchronous errors via Global Error Handler
- ✅ Asynchronous errors via Promise Rejection Tracker
- ✅ Multi-engine support (Hermes, JavaScriptCore, Web)
- ✅ Zero dependencies (React Native peer dependency only)
- ✅ TypeScript support with full type definitions
- ✅ Expo compatible - works out of the box
---
bash
npm install react-native-comprehensive-error-handler react-native-safe-area-context
`$3
bash
npx expo install react-native-comprehensive-error-handler react-native-safe-area-context
`> 💡 Note: With npm 7+, peer dependencies install automatically. The above command will install both packages in one go.
---
🚀 Quick Start
Wrap your app with
:`typescript
import { GlobalErrorBoundary } from 'react-native-comprehensive-error-handler';function App() {
return (
console.log('Error caught:', error);
// Optional: Send to your error reporting service
}}
>
);
}
`That's it! 🎉 All errors are now caught and handled gracefully.
---
📖 API Reference
$3
The main component that wraps your app and handles all errors.
#### Props
| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
|
| ReactNode | ✅ | - | Your app content |
| config | GlobalErrorBoundaryConfig | ❌ | See below | Error handling configuration |
| onError | (error, errorType, errorInfo) => void | ❌ | - | Callback when error is caught |
| fallbackComponent | ComponentType | ❌ | DefaultFallback | Custom error UI |---
⚙️ Configuration
$3
`typescript
{
enableRenderErrors: true, // Catch React render errors
enableSyncErrors: true, // Catch synchronous JS errors
enableAsyncErrors: true, // Catch async/promise errors
suppressDefaultHandler: true // Suppress red screen in dev
}
`$3
typescript
enableRenderErrors: true,
enableSyncErrors: true,
enableAsyncErrors: true,
suppressDefaultHandler: true
}}
onError={(error, errorType, errorInfo) => {
// Your error handling logic
if (__DEV__) {
console.log(error);
} else {
// Send to Sentry, Firebase, etc.
yourErrorService.report(error);
}
}}
>
`---
🎨 Custom Fallback UI
Provide your own error screen:
typescript
import { FallbackComponentProps } from 'react-native-comprehensive-error-handler';function CustomErrorScreen({ error, errorType, errorInfo, resetError }: FallbackComponentProps) {
return (
Oops! Something went wrong
{error.message}
);
}
`---
🔄 Programmatic Error Reset
Use a ref to reset errors programmatically:
typescript
import { useRef } from 'react';
import { GlobalErrorBoundary, GlobalErrorBoundaryRef } from 'react-native-comprehensive-error-handler';function App() {
const errorBoundaryRef = useRef(null);
const handleReset = () => {
errorBoundaryRef.current?.resetError();
};
const checkError = () => {
const currentError = errorBoundaryRef.current?.getCurrentError();
if (currentError) {
console.log('Current error:', currentError);
}
};
return (
);
}
`
---
🧪 Testing
Test different error types to verify error handling:
typescript
// Render error
const ThrowRenderError = () => {
throw new Error('Test render error');
return null;
};// Sync error
const throwSyncError = () => {
throw new Error('Test sync error');
};
// Async error
const throwAsyncError = async () => {
await Promise.reject(new Error('Test async error'));
};
`---
🌐 Platform Support
| Platform | Render Errors | Sync Errors | Async Errors |
|----------|---------------|-------------|--------------|
| iOS (Hermes) | ✅ | ✅ | ✅ |
| iOS (JSC) | ✅ | ✅ | ✅ |
| Android (Hermes) | ✅ | ✅ | ✅ |
| Android (JSC) | ✅ | ✅ | ✅ |
| Web | ✅ | ⚠️* | ✅ |
| Expo | ✅ | ✅ | ✅ |
*Web sync errors are logged but may not trigger fallback UI due to browser behavior.
---
📝 TypeScript Support
Full TypeScript definitions included:
typescript
import {
GlobalErrorBoundary,
GlobalErrorBoundaryProps,
GlobalErrorBoundaryConfig,
GlobalErrorBoundaryRef,
FallbackComponentProps,
ErrorType,
ErrorState,
JSEngine,
} from 'react-native-comprehensive-error-handler';
`---
🔧 How It Works
$3
┌────────────────────────────────────────────┐
│ GlobalErrorBoundary │
└───────┬──────────────┬─────────────┬───────┘
│ │ │
┌────▼────┐ ┌────▼───┐ ┌────▼────────┐
│ Render │ │ Sync │ │ Async │
│ Error │ │ Error │ │ Error │
└────┬────┘ └───┬────┘ └────┬────────┘
│ │ │
┌────▼────────┐ ┌──▼─────────┐ ┌──▼───────────┐
│ React │ │ ErrorUtils │ │ Promise │
│ Boundary │ │ │ │ Tracker │
│ │ │ │ │(Multi-Engine)│
└─────────────┘ └────────────┘ └──────────────┘
$3
Automatically detects and uses the appropriate promise rejection tracking:
- Hermes:
- JSC: module
- Web: window.unhandledrejection event---
🤔 FAQ
$3
A: No! This package works perfectly with Expo without any configuration.$3
A: No, this only catches JavaScript errors. Native crashes require platform-specific crash reporting tools.$3
A: Minimal. Error handlers are lightweight and only active when errors occur.$3
A: Yes! Use the config prop to disable any error type you don't want to catch.$3
A: Yes! Simply check the error in your onError callback and decide whether to report it or not. You can also call resetError()` immediately for errors you want to dismiss.---
- GitHub Repository
- Medium Article
---
Contributions are welcome! Please open an issue or submit a pull request.
---
MIT © Vikas Reddy
---
Made with ❤️ for the React Native community