ez-fe-error-handler
v1.0.3
Published
Global & Component error reporting for React & Next.js with email alerts
Maintainers
priya-ezReadme
ez-fe-error-handler
Automated error monitoring with instant email alerts for React & Next.js applications
Never miss critical production errors again. ez-fe-error-handler automatically captures and reports React errors, unhandled promise rejections, and global JavaScript errors directly to your email inbox with detailed device information and stack traces.
Features
- 🚨 Automatic Error Detection - Catches React component errors, promise rejections, and global errors
- 📧 Instant Email Alerts - Get notified immediately when errors occur in production
- 🔍 Rich Error Context - Includes stack traces, page URL, browser, OS, IP address, and timestamp
- ⚡ Zero Config Setup - Simple integration with just a few lines of code
- 🎯 Framework Support - Works seamlessly with both React and Next.js (App Router & Pages Router)
- 🛡️ Type-Safe - Written in TypeScript with full type definitions
Installation
npm install ez-fe-error-handlerPeer Dependencies
npm install react react-dom react-error-boundaryQuick Start
Next.js (App Router)
1. Create an Error Provider Component
// app/ErrorProviders.tsx
"use client";
import {
ClientErrorInit,
ClientErrorBoundary,
configureErrorReceiverEmails,
configureApiUrl,
} from "ez-fe-error-handler";
// Configure email recipients
const emails = process.env.NEXT_PUBLIC_ERROR_RECEIVER_EMAILS?.split(",") || [];
configureErrorReceiverEmails({ emails });
configureApiUrl(process.env.NEXT_PUBLIC_API_URL);
export default function ErrorProviders({
children,
}: {
children: React.ReactNode;
}) {
return (
<>
<ClientErrorInit />
<ClientErrorBoundary>{children}</ClientErrorBoundary>
</>
);
}2. Wrap Your App in the Root Layout
// app/layout.tsx
import ErrorProviders from "./ErrorProviders";
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<html lang="en">
<body>
<ErrorProviders>{children}</ErrorProviders>
</body>
</html>
);
}React (Vite/CRA)
// main.tsx or index.tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import App from "./App";
import {
ClientErrorBoundary,
ClientErrorInit,
configureErrorReceiverEmails,
configureApiUrl,
} from "ez-fe-error-handler";
// Configure email recipients
const emails =
import.meta.env.VITE_ERROR_RECEIVER_EMAILS?.split(",").map((email: string) =>
email.trim()
) || [];
const apiUrl = import.meta.env.VITE_APP_EMAIL_API_URL;
configureErrorReceiverEmails({ emails });
configureApiUrl(apiUrl);
createRoot(document.getElementById("root")!).render(
<StrictMode>
<ClientErrorBoundary>
<ClientErrorInit />
<App />
</ClientErrorBoundary>
</StrictMode>
);Configuration
API Endpoint
Set your email service API endpoint:
configureApiUrl("https://your-backend.com/api/v1/send-email");The API endpoint should accept POST requests with the following structure:
{
"recipients": ["[email protected]", "[email protected]"],
"subject": "Production Error Alert",
"email_content": "<html>...</html>"
}Email Format
Error emails include comprehensive debugging information:
- Error Message - The actual error that occurred
- Page URL - Where the error happened
- Browser - Chrome, Firefox, Safari, Edge, etc.
- Operating System - Windows, macOS, Linux, iOS, Android
- IP Address - User's IP for additional context
- Timestamp - When the error occurred (IST timezone)
- Stack Trace - Full error stack for debugging
API Components
configureErrorReceiverEmails(config)
Set up email recipients for error notifications.
Parameters:
config.emails(string[]): Array of email addresses
configureApiUrl(url)
Configure the email service endpoint.
Parameters:
url(string): Your email API endpoint URL
<ClientErrorBoundary>
React Error Boundary component that catches component errors.
Props:
children(ReactNode): Your app components
<ClientErrorInit>
Initializes global error handlers for promise rejections and window errors.
Usage: Place at the top level of your app (no props needed)
Error Types Captured
- React Component Errors - Errors during rendering, lifecycle methods, or constructors
- Unhandled Promise Rejections - Async errors that weren't caught
- Global JavaScript Errors - Runtime errors anywhere in your application
Environment Considerations
The package is designed for client-side only and includes SSR checks. It won't execute on the server in Next.js applications.
Production vs Development
While the package works in all environments, you may want to conditionally enable it:
const isProduction = process.env.NODE_ENV === "production";
if (isProduction) {
configureErrorReceiverEmails({
emails: ["[email protected]"],
});
configureApiUrl("https://api.company.com/send-email");
}Best Practices
- Use Environment Variables - Store email API URLs in environment variables
- Separate Alert Channels - Use different emails for staging vs production
- Rate Limiting - Implement rate limiting on your email API to prevent spam
- Error Deduplication - Consider implementing error grouping on your backend
- Privacy Compliance - Ensure IP collection complies with your privacy policy
Backend API Example
Your email endpoint should handle requests like:
// Example Express.js endpoint
app.post("/api/v1/send-email", async (req, res) => {
const { recipients, subject, email_content } = req.body;
// Send email using your preferred service (SendGrid, AWS SES, etc.)
await sendEmail({
to: recipients,
subject: subject,
html: email_content,
});
res.status(200).json({ success: true });
});Troubleshooting
Emails Not Being Sent
- Verify
configureApiUrl()is called before errors occur - Check that
configureErrorReceiverEmails()has valid email addresses - Ensure your API endpoint is accessible from the client
- Check browser console for any fetch errors
Errors Not Being Caught
- Ensure
<ClientErrorBoundary>wraps your entire app - Verify
<ClientErrorInit />is rendered at the top level - Check that the package is installed correctly with peer dependencies
License
MIT