Error Boundary в React
Error Boundary (граница ошибок) в React — компонент, который ловит ошибку при отрисовке своих потомков и показывает запасной интерфейс вместо упавшего дерева. Без него одна ошибка в любом компоненте размонтирует всё приложение, и посетитель увидит белую страницу.
Ниже — что Error Boundary ловит и чего не ловит, как написать свой, когда взять библиотеку react-error-boundary, что изменилось в React 19 и как отправлять пойманные ошибки в мониторинг, чтобы о них узнавали вы, а не служба поддержки.
Что такое Error Boundary в React
Начиная с React 16 необработанная ошибка при рендере размонтирует всё дерево от корня. Логика простая: лучше пустой экран, чем интерфейс в неконсистентном состоянии, где кнопка «Оплатить» показывает чужую сумму.
Error Boundary ограничивает ущерб. Если упал компонент внутри границы, React заменит на запасной интерфейс только эту часть, а остальное приложение продолжит работать. Обычно ставят одну границу вокруг всего приложения — «Что-то пошло не так, обновите страницу» — и несколько локальных: вокруг виджета, боковой панели, отдельной страницы маршрута.
Что ловит Error Boundary и чего не ловит
Граница ловит ошибки, которые React видит в процессе отрисовки дерева под ней:
- в
renderи теле функциональных компонентов; - в конструкторах и методах жизненного цикла классов;
- в
useEffect,useLayoutEffectи других хуках; - при загрузке
lazy-компонента внутриSuspense, напримерChunkLoadErrorпосле выкладки.
Не ловит:
| Ошибка | Почему | Что делать |
|---|---|---|
В обработчиках событий (onClick, onSubmit) |
обработчик вызывается не во время рендера | try/catch внутри обработчика |
В асинхронном коде: setTimeout, fetch().then, async-функции |
код выполняется после того, как рендер закончился | try/catch с await, .catch() у промиса |
| При серверном рендеринге (SSR) | границы работают только в браузере | обработка ошибок на сервере |
| В самой границе | граница не может поймать собственную ошибку | ошибка уходит к ближайшей границе выше |
Ошибку из обработчика или асинхронного кода можно отдать границе вручную: сохраните её в состоянии и бросьте при следующем рендере.
const [error, setError] = useState<unknown>(null);
if (error) throw error; // теперь ошибку поймает ближайшая граница
async function onSave() {
try {
await saveOrder();
} catch (e) {
setError(e);
}
}В React 19 так же к ближайшей границе доходит ошибка из асинхронной функции, переданной в startTransition.
Пример Error Boundary на классовом компоненте
Хука для границы ошибок в React нет — нужен классовый компонент с одним или двумя методами:
static getDerivedStateFromError(error)— возвращает новое состояние, чтобы показать запасной интерфейс;componentDidCatch(error, info)— побочные действия: запись в лог или отправка в мониторинг. Вinfo.componentStack— цепочка компонентов до упавшего.
import { Component, type ErrorInfo, type ReactNode } from 'react';
type Props = { fallback: ReactNode; children: ReactNode };
type State = { hasError: boolean };
export class ErrorBoundary extends Component<Props, State> {
state: State = { hasError: false };
static getDerivedStateFromError(): State {
return { hasError: true };
}
componentDidCatch(error: Error, info: ErrorInfo) {
console.error(error, info.componentStack);
}
render() {
return this.state.hasError ? this.props.fallback : this.props.children;
}
}<ErrorBoundary fallback={<p>Не удалось загрузить отчёт.</p>}>
<Report />
</ErrorBoundary>В режиме разработки React всё равно показывает пойманную ошибку в консоли и в оверлее сборщика. Это нормально: в собранном приложении посетитель увидит только fallback.
react-error-boundary
Чтобы не писать класс самому, берут библиотеку react-error-boundary. Она умеет то, что в простом примере пришлось бы дописывать: сброс ошибки, сброс по смене ключей, хук для асинхронного кода.
import { ErrorBoundary, useErrorBoundary } from 'react-error-boundary';
function Fallback({ error, resetErrorBoundary }) {
return (
<div role="alert">
<p>Что-то пошло не так.</p>
<button onClick={resetErrorBoundary}>Попробовать снова</button>
</div>
);
}
<ErrorBoundary FallbackComponent={Fallback} resetKeys={[userId]}>
<Profile userId={userId} />
</ErrorBoundary>;resetKeys сбрасывает ошибку, когда меняется значение: пользователь открыл другой профиль — граница пробует отрисовать его заново. Хук useErrorBoundary даёт функцию showBoundary(error): вызовите её в catch асинхронного кода, и ошибка уйдёт к границе.
onUncaughtError и onCaughtError в React 19
В React 19 у createRoot появились обработчики ошибок всего приложения:
onUncaughtError— ошибка, которую не поймала ни одна граница: дерево размонтировано;onCaughtError— ошибка, которую поймала граница и показалаfallback;onRecoverableError— ошибка, после которой React восстановился сам (например, расхождение при гидратации).
createRoot(document.getElementById('root')!, {
onUncaughtError: (error, info) => report(error, info.componentStack),
onCaughtError: (error, info) => report(error, info.componentStack),
}).render(<App />);Это удобная точка, чтобы отправлять все ошибки рендера в одно место, а не дописывать componentDidCatch в каждую границу. Сами границы всё равно нужны: обработчики только сообщают об ошибке, запасной интерфейс рисует граница.
Как отправлять ошибки Error Boundary в мониторинг
console.error в componentDidCatch видят только те, у кого открыты DevTools, — то есть не посетители. Чтобы узнавать об ошибках, которые случаются у людей, их нужно отправлять в систему мониторинга вместе со стеком компонентов.
В пакете @nablops/react есть готовая граница nabl.ErrorBoundary. Она ловит ошибку рендера, отправляет её в NablOps со стеком компонентов и показывает fallback:
import * as nabl from '@nablops/react';
nabl.init({ key: 'pk_…' });
createRoot(document.getElementById('root')!, {
onUncaughtError: nabl.reactErrorHandler(),
onCaughtError: nabl.reactErrorHandler(),
}).render(
<nabl.ErrorBoundary fallback={({ resetError }) => <ErrorScreen onRetry={resetError} />} tags={{ area: 'app' }}>
<App />
</nabl.ErrorBoundary>,
);fallback— элемент или функция, которая получаетerror,componentStackиresetError(). Безfallbackна месте упавшего дерева ничего не рисуется.onError(error, componentStack)вызывается после отправки,onReset— приresetError().tags— теги события, по ним удобно отличать ошибки разных частей приложения.nabl.reactErrorHandler()подходит дляonUncaughtError,onCaughtErrorиonRecoverableErrorв React 19. Ошибка, которую уже отправила граница, второй раз изonCaughtErrorилиwindow.onerrorне уходит.
Ошибки из обработчиков событий и асинхронного кода, до которых граница не дотягивается, пакет ловит сам — через window.onerror и отклонённые промисы. Если такую ошибку вы поймали и обработали, но знать о ней хотите, отправьте её вручную: nabl.captureException(err).
Уже используете react-error-boundary? Оставьте его и отправляйте ошибку из onError:
<ErrorBoundary
FallbackComponent={Fallback}
onError={(error, info) => nabl.captureException(error, { componentStack: info.componentStack ?? undefined })}
>Где в ваших компонентах упала ошибка
В NablOps ошибка фронтенда появляется на вкладке «Ошибки» с пометкой «ошибка рендера React». На её странице есть блок «Компоненты React» — цепочка компонентов до упавшего, а также браузеры, системы, страницы и затронутые сессии.
В продакшене код минифицирован, и стек без карт выглядит как at Xo (index-B3x.js:1:48213). Если сборка загружает source maps (@nablops/vite-plugin для Vite или @nablops/cli для других сборщиков), в стеке видны ваш файл, функция, строка и код вокруг неё, а для упавшего компонента — где в ваших компонентах это случилось. Карты на сайт не выкладываются: посетители их не видят.
Разобрать ошибку можно и через ИИ-ассистента: он видит стек, компоненты и сессию, в которой ошибка случилась.
Что дальше
- Мониторинг ошибок React — подключение
@nablops/reactза несколько минут. - Source maps — исходный код вместо минифицированного бандла.
- Сессии и пользователи — что делал посетитель перед ошибкой.
- ChunkLoadError после выкладки — частая ошибка, которую ловит граница вокруг
lazy.
Первый сервер или стек подключается за пару минут. Бесплатно в раннем доступе.
Нашли неточность или не хватает ответа? Напишите в поддержку