@heritsilavo/react-error-boundary

A robust error boundary component for React and Next.js applications with customizable error handling and display.

Features

🛡️ Comprehensive error boundary for React and Next.js
🎨 Customizable error display component
⏱️ Auto-hide functionality with progress indicator
🚦 Error context for centralized error management
📦 Supports both CommonJS and ES Modules
🏷️ Fully typed with TypeScript
⚛️ React 18+ compatible
⏭️ Next.js 13+ support

Installation

npm install @heritsilavo/react-error-boundary
# or
yarn add @heritsilavo/react-error-boundary
# or
pnpm add @heritsilavo/react-error-boundary

Peer Dependencies

This package requires:

React 18+
React DOM 18+
For Next.js usage: Next.js 13+

Basic Usage

For React Applications

import { ErrorProvider } from '@heritsilavo/react-error-boundary';

function App() {
  return (
    <ErrorProvider>
      <YourApp />
    </ErrorProvider>
  );
}

For Next.js Applications

import { ErrorProvider } from '@heritsilavo/react-error-boundary/next';

function App({ Component, pageProps }) {
  return (
    <ErrorProvider>
      <Component {...pageProps} />
    </ErrorProvider>
  );
}

Advanced Usage

Custom Error Component

import { ErrorProvider } from '@heritsilavo/react-error-boundary';
import type { ErrorComponentType } from '@heritsilavo/react-error-boundary';

function CustomError({ error, onClose }: ErrorComponentType) {
  return (
    <div className="custom-error">
      <h3>Error: {error.code}</h3>
      <p>{error.message}</p>
      {error.description && <small>{error.description}</small>}
      <button onClick={onClose}>Close</button>
    </div>
  );
}

function App() {
  return (
    <ErrorProvider 
      ErrorComponent={CustomError}
      autoHideDelay={10000}
    >
      <YourApp />
    </ErrorProvider>
  );
}

Throwing Custom Errors

import { useThrowError } from '@heritsilavo/react-error-boundary';

function MyComponent() {
  const throwError = useThrowError();

  const handleClick = () => {
    try {
      // Your code that might fail
    } catch (err) {
      throwError(
        'API_ERROR',
        'Failed to fetch data',
        err.message
      );
    }
  };

  return <button onClick={handleClick}>Fetch Data</button>;
}

Accessing Error Context

import { useError } from '@heritsilavo/react-error-boundary';

function StatusIndicator() {
  const { error, clearError } = useError();

  if (!error) return null;

  return (
    <div>
      <span>Error: {error.message}</span>
      <button onClick={clearError}>Dismiss</button>
    </div>
  );
}

API Reference

Components

`ErrorProvider`

The root provider component that sets up the error boundary and context.

Props:

Prop	Type	Default	Description
`children`	ReactNode	required	Your application components
`ErrorComponent`	ComponentType	`DefaultErrorComponent`	Custom error display component
`autoHideDelay`	number	5000	Time in ms before auto-hiding (0 to disable)
`onError`	() => void	() => {}	Callback when error occurs
`closeErrorComponetOnClick`	boolean	false	Close error component when clicked

`ErrorBoundary`

The actual error boundary component (used internally by ErrorProvider but can be used directly if needed).

Hooks

`useError()`

Returns the error context with:

error: CustomError | null - Current error object
handleError: (error: Error) => void - Function to trigger errors
clearError: () => void - Function to clear current error

`useThrowError()`

Returns a convenience function to throw custom errors: (code: string, message: string, description: string) => void

Types

`CustomError`

Custom error class with:

code: string
message: string
description: string

`ErrorComponentType`

Type for custom error components with props:

error: CustomError
onClose: () => void
closeOnClick?: boolean
visiblityTime?: number

Styling

The default error component comes with basic styling that can be overridden with CSS variables:

:root {
  --tsila-err-color: #ff4444;
  --tsila-err-bg: #fff;
  --tsila-err-border: 1px solid #ff4444;
  --tsila-err-padding: 1rem;
  --tsila-err-border-radius: 4px;
  --tsila-err-box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}

Examples

Handling API Errors

import { useThrowError } from '@heritsilavo/react-error-boundary';

function DataFetcher() {
  const throwError = useThrowError();
  const [data, setData] = useState(null);

  const fetchData = async () => {
    try {
      const response = await fetch('/api/data');
      if (!response.ok) {
        throwError(
          'FETCH_FAILED',
          'Failed to load data',
          `Server returned ${response.status}`
        );
        return;
      }
      setData(await response.json());
    } catch (err) {
      throwError(
        'NETWORK_ERROR',
        'Network request failed',
        err.message
      );
    }
  };

  // ...
}

Custom Error Boundary in Next.js

// pages/_app.tsx
import { ErrorProvider } from '@heritsilavo/react-error-boundary/next';
import { CustomErrorPage } from '../components/CustomErrorPage';

export default function App({ Component, pageProps }) {
  return (
    <ErrorProvider 
      ErrorComponent={CustomErrorPage}
      autoHideDelay={0} // Disable auto-hide
      closeErrorComponetOnClick={true}
    >
      <Component {...pageProps} />
    </ErrorProvider>
  );
}

Contributing

Contributions are welcome! Please open an issue or submit a pull request.