@elcrm/error-boundary

React Error Boundary для elCRM: перехват ошибок рендера в поддереве, кастомный fallback, maxRetry, фабрика createErrorBoundary. Реализован как классовый компонент (в React только так можно перехватывать ошибки рендера).

Установка

npm install @elcrm/error-boundary
# или
bun add @elcrm/error-boundary

Требования: Node.js ≥ 18. Peer-зависимости: react ≥ 18, react-dom ≥ 18.

Для разработки пакета удобен Bun ≥ 1.3 (см. dev.md, deploy.md).

Использование

import React from "react";
import { ErrorBoundary } from "@elcrm/error-boundary";

export function Example() {
    return (
        <ErrorBoundary
            fallback={
                <div className="error-fallback">
                    <h2>Ошибка</h2>
                    <p>Произошла ошибка в дочернем компоненте.</p>
                </div>
            }
        >
            <div>
                Чувствительный к ошибкам контент. При ошибке будет показан
                переданный fallback.
            </div>
        </ErrorBoundary>
    );
}

Пропсы

| Проп | Тип | Описание | | ------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | children | React.ReactNode | Содержимое, ошибки рендера которого перехватываются. | | fallback | React.ReactNode | Необязательно. Если проп передан (в т.ч. null), при ошибке показывается только он в обёртке с role="alert" и классом error-fallback. Объект ошибки в этот узел не подставляется — используйте FallbackComponent, если нужны error и сброс. | | FallbackComponent | React.ComponentType<TErrorBoundaryFallbackProps> | Кастомный фоллбек с данными об ошибке и опциональной кнопкой сброса. Используется, если проп fallback не задан. | | maxRetry | number | Максимальное число успешных нажатий «Повторить» (сброс границы и повторный рендер детей). По умолчанию Infinity — без ограничений. Счётчик увеличивается после каждого сброса. |

Приоритет при ошибке

1. Задан fallback → показывается только он.
2. Иначе, если задан FallbackComponent → рендерится он с пропсами error и при необходимости resetError.
3. Иначе — встроенный экран: сообщение, стек (если есть), кнопки «Повторить» (если лимит не исчерпан) и «Обновить страницу».

Типы (TypeScript)

• TErrorBoundaryProps — пропсы границы.
• TErrorBoundaryFallbackProps — пропсы для FallbackComponent:

type TErrorBoundaryFallbackProps = {
    error: Error;
    /** Сброс границы и повторный рендер детей (если не исчерпан maxRetry). */
    resetError?: () => void;
};

Алиас DefaultErrorBoundary

DefaultErrorBoundary — то же самое, что и ErrorBoundary (удобно, если в проекте уже есть своё имя ErrorBoundary).

import { DefaultErrorBoundary } from "@elcrm/error-boundary";

<DefaultErrorBoundary fallback={<div>Ошибка произошла</div>}>
    <RiskyComponent />
</DefaultErrorBoundary>;

Примеры фоллбека

Встроенный UI (без fallback и без FallbackComponent)

Показывается заголовок, текст ошибки, опционально стек, «Повторить» (если разрешено maxRetry), «Обновить страницу».

<ErrorBoundary>
    <SomeComponent />
</ErrorBoundary>

Кастомный компонент с error и «Повторить»

import type { TErrorBoundaryFallbackProps } from "@elcrm/error-boundary";

function CustomFallback({ error, resetError }: TErrorBoundaryFallbackProps) {
    return (
        <div role="alert">
            <h2>Произошла ошибка</h2>
            <pre>{error.message}</pre>
            {resetError ? (
                <button type="button" onClick={resetError}>
                    Повторить
                </button>
            ) : null}
            <button type="button" onClick={() => window.location.reload()}>
                Обновить
            </button>
        </div>
    );
}

<ErrorBoundary FallbackComponent={CustomFallback} maxRetry={3}>
    <SomeComponent />
</ErrorBoundary>;

Фабрика createErrorBoundary

Возвращает компонент-обёртку с зафиксированными опциями; пропсы при использовании перекрывают опции фабрики.

import { createErrorBoundary } from "@elcrm/error-boundary";

const ErrorWithFallback = createErrorBoundary({
    fallback: (
        <>
            <h2>Ошибка</h2>
            <p>Что-то пошло не так.</p>
        </>
    ),
});

<ErrorWithFallback>
    <SomeComponent />
</ErrorWithFallback>;

Какие ошибки перехватываются

React Error Boundary обрабатывает только необработанные исключения при рендере, в lifecycle и в конструкторах дочерних компонентов. Обычный try/catch вокруг рендера не заменяет границу: пойманное исключение до границы не дойдёт.

// Не покажет fallback границы: ошибка уже поймана
try {
    throw new Error("ОШИБКА");
} catch (err) {
    console.error(err);
}

<ErrorBoundary>{/* фоллбек не появится */}</ErrorBoundary>;

Ошибка в дочернем классовом компоненте при рендере — типичный случай для границы:

export class Example extends React.Component<{ message: string }> {
    render() {
        throw new Error("Всегда вызывает ошибку");
    }
}

<ErrorBoundary fallback={<div>Ошибка</div>}>
    <Example message="" />
</ErrorBoundary>;

Вывод в консоль

ErrorBoundary в componentDidCatch вызывает console.error для ошибки и для errorInfo (стек компонентов).

export class BrokenComponent extends React.Component {
    render() {
        throw new Error("Тест ошибки");
    }
}

<ErrorBoundary>
    <BrokenComponent />
</ErrorBoundary>;

Рекомендации

1. Оборачивайте только те участки дерева, где возможны ошибки рендера, чтобы не скрывать сбои слишком широко.
2. Не полагайтесь на try/catch вместо границы для ошибок внутри того же React-дерева — граница и try/catch решают разные задачи.
3. Статичный fallback — для простого текста; для показа error.message и кнопки сброса используйте FallbackComponent.
4. Ограничивайте число повторов через maxRetry, если не хотите бесконечных циклов «упал → повторил» при стабильно падающем коде.
5. Если кастомный фоллбек не нужен, не передавайте fallback — сработает встроенный экран с сообщением и действиями.

Экспорт

| Имя | Описание | | --- | -------- | | ErrorBoundary | Основной класс-компонент | | DefaultErrorBoundary | Алиас ErrorBoundary | | createErrorBoundary | Фабрика с зафиксированными опциями | | TErrorBoundaryProps | Тип пропсов границы | | TErrorBoundaryFallbackProps | Тип пропсов FallbackComponent |

Разработка и публикация

• Локальный стенд: bun run dev → test/README.md
• Тесты: bun test
• Сборка: bun run build
• Публикация на npm: deploy.md

Лицензия

MIT © MaSkal