Мониторинг ошибок фронтенда на React
Мониторинг ошибок фронтенда в NablOps показывает ошибки JavaScript, которые случаются у ваших посетителей прямо в браузере: исключения, отклонённые промисы, падения компонентов React и не загрузившиеся после выкладки части приложения. Агент стека их не видит — браузер работает на компьютере пользователя, а не в вашем контейнере. Поэтому в проект добавляется фронтенд, а в приложение — пакет @nablops/react из npm.
Если вы искали замену Sentry для React-приложения, это она: ошибки браузера, бэкенда и инфраструктуры живут в одном проекте, а из ошибки фронтенда можно перейти в трассу запроса на сервере.
Что ловит пакет @nablops/react
| Что | Как попадает в NablOps |
|---|---|
Необработанные исключения (window.onerror) |
ошибка со стеком, браузером, системой и страницей |
Отклонённые промисы без catch |
ошибка со стеком, если промис отклонён объектом Error |
| Падение компонента при рендере | через ErrorBoundary — вместе со стеком компонентов React |
Не загрузившийся чанк после выкладки (ChunkLoadError) |
одна ошибка на релиз, подробнее — ChunkLoadError |
| Не загрузившиеся скрипты, стили и картинки | ошибка загрузки ресурса |
| Свои ошибки и сообщения | nabl.captureException(err), nabl.captureMessage('…', 'warning') |
К каждой ошибке пакет прикладывает контекст: браузер, систему, устройство, страницу, релиз и последние 50 действий — переходы, клики по кнопкам и ссылкам, console.error, запросы к API.
Шум отбрасывается ещё в браузере: ошибки расширений, ResizeObserver loop, Script error. без стека, отменённые запросы, боты и headless-браузеры. Одна и та же ошибка уходит не чаще раза в 10 секунд и не больше 30 ошибок за сессию — бесконечный цикл ошибок не забьёт ни канал посетителя, ни ваш проект.
Как подключить мониторинг ошибок React
1. Добавьте фронтенд в проект
На странице проекта нажмите «Добавить» → «Фронтенд». Укажите:
- Название — например, «Личный кабинет» или «Сайт».
- Домены приложения — адреса, с которых приложение работает:
https://app.example.com. Поддомены — шаблономhttps://*.example.com. События с других доменов не принимаются. - Принимать с localhost — для разработки, с любым портом.
- Сборщик — Vite, Next.js, Webpack / CRA или другой: от него зависит код подключения.
Один фронтенд — одно приложение одного окружения. Сайт и личный кабинет — два фронтенда в одном проекте; production и staging — разные проекты, у каждого свой фронтенд со своим ключом. Подробнее — в основных понятиях.
2. Установите пакет и вызовите init
Мастер покажет код с уже вписанным публичным ключом pk_… и адресом приёма. Пакет нужен React 18 или новее:
npm i @nablops/reactВ точке входа (src/main.tsx у Vite) — до рендера приложения:
import * as nabl from '@nablops/react';
nabl.init({
key: 'pk_…',
endpoint: 'https://app.nablops.io/nabl',
});Публичный ключ не секрет: он попадает в бандл, а от злоупотребления защищают список доменов, лимиты и суточная квота. Переменная окружения или секрет CI для него не нужны.
Версию сборки release у Vite вписывает @nablops/vite-plugin — передавать её в init не нужно. У Next.js и webpack мастер показывает строку с переменной сборки.
3. Оберните приложение в ErrorBoundary
createRoot(document.getElementById('root')!, {
// React 19: ошибки, которые React перехватил сам
onUncaughtError: nabl.reactErrorHandler(),
onCaughtError: nabl.reactErrorHandler(),
}).render(
<nabl.ErrorBoundary fallback={<p>Что-то пошло не так</p>}>
<App />
</nabl.ErrorBoundary>,
);ErrorBoundary ловит ошибку рендера, отправляет её со стеком компонентов и показывает fallback. Ошибка, уже отправленная границей, второй раз из onCaughtError или window.onerror не уходит. Хуки onUncaughtError и onCaughtError есть только в React 19; в React 18 достаточно ErrorBoundary. Как ставить несколько границ, передавать теги и кнопку «Повторить» — в статье ErrorBoundary.
4. Подключите React Router
Чтобы ошибки группировались по странице (/projects/:id), а не по каждому адресу (/projects/42), оберните создание роутера React Router 7:
const router = nabl.wrapCreateBrowserRouter(createBrowserRouter)(routes);Переходы в хронологии тоже попадут шаблонами. Для другого роутера сообщайте шаблон сами: nabl.setRoute('/projects/:id').
5. Проверьте подключение
Откройте приложение в браузере. Мастер сам заметит первое событие и напишет «Подключено — из приложения пришло первое событие», а у фронтенда появится статус «пакет подключён». Если у сайта есть Content-Security-Policy, добавьте в неё connect-src https://app.nablops.io.
Если события не приходят, откройте консоль браузера:
| Что видно | Причина |
|---|---|
403 на запрос к /nabl |
домен страницы не указан в «Доменах приложения» (для локальной разработки — включите «Принимать с localhost») |
401 |
неверный ключ: опечатка или ключ перевыпущен больше суток назад |
| запрос заблокирован политикой | Content-Security-Policy без адреса NablOps в connect-src |
запросов к /nabl нет |
init не вызван или вызван позже ошибки |
Как группируются ошибки фронтенда
Одинаковые ошибки собираются в одну запись со счётчиком, браузерами, системами и страницами. С source maps ошибка определяется типом исключения и ближними кадрами вашего кода — функцией и файлом исходника, без текста сообщения и номеров строк. Поэтому один баг в Chrome («Cannot read properties of undefined») и в Safari («undefined is not an object») — одна запись, а новая выкладка того же кода не плодит новых ошибок.
Без карт ошибка определяется типом, текстом и файлом бандла без хэша сборки — разные браузеры с разным текстом тогда дают разные записи.
Вкладки фронтенда в кабинете
У каждого фронтенда своя страница с вкладками:
| Вкладка | Что внутри |
|---|---|
| «Обзор» | сессии, доля сессий без сбоев, пользователи, сравнение с прошлым периодом и по релизам — сессии и пользователи |
| «Ошибки» | ошибки фронтенда с теми же статусами, что у ошибок приложения: открыта, решена, без уведомлений |
| «Сессии» | сессии посетителей и поиск по пользователю |
| «Запросы» | обращения к API из браузеров — запросы и трасса бэкенда |
| «Релизы» | версии сборки, выкладки, загружены ли карты — source maps и релизы |
| «События» | лента фронтенда: новые ошибки, выкладки, уведомления |
| «Настройки» | домены, ключ, код подключения, source maps и доверенная сборка |
На странице ошибки фронтенда — стек (по исходному коду, если загружены карты), блок «Компоненты React», где случается ошибка: браузеры, системы, страницы и пользователи, а у каждого повтора — ссылка на его сессию и «трасса запроса», если ошибка случилась после упавшего запроса. Открытая ошибка без повторов 7 дней закрывается сама, как у бэкенда.
Персональные данные в ошибках
Почта, телефоны, номера карт и токены в текстах ошибок и адресах маскируются при приёме, до записи; токены в путях заменяются на :token (/invite/:token). Значения полей ввода пакет не собирает вовсе, а у кликов запоминает только селектор и текст кнопки. Текст элемента внутри data-nabl-private не берётся — так можно скрыть, например, имя клиента в шапке. Перед отправкой событие можно поправить или отбросить на клиенте опцией beforeSend, известный шум — отфильтровать ignoreErrors.
Пакет не ломает приложение: все перехватчики обёрнуты в try/catch, ваши обработчики window.onerror не заменяются, повторный init() при HMR или в StrictMode перехватчики второй раз не ставит.
Уведомления о новых ошибках фронтенда
О новой ошибке фронтенда NablOps сообщает сразу, в каналы проекта. Чтобы плохая выкладка не завалила чат, о новых ошибках одного фронтенда приходит не больше 5 сообщений в час, остальные — одной сводкой. Без очереди, даже когда лимит часа исчерпан, приходят:
- ошибка, которую поймали два и больше посетителя (разные сессии);
- ошибка у вошедшего пользователя — если приложение вызывает
nabl.setUser({ id }).
Известный шум переведите в «Без уведомлений» на странице ошибки. Отдельное правило следит за долей сессий без сбоев. Каналы и уровни настраиваются в правилах уведомлений.
Фронтенд на карте проекта и в покрытии
Фронтенды видны в дереве проекта, карточками на странице проекта (открытые ошибки и доля сессий без сбоев за сутки) и в ленте событий. На карте проекта каждый фронтенд — павильон-витрина перед зданием: пока пакет не подключён, витрина заколочена, без source maps стекло матовое, а когда всё подключено — витрина светится. Ошибки за последний час — трещины на стекле.
В покрытии проекта фронтенд даёт шаги «Пакет фронтенда … не подключён» и «Нет source maps у релиза …». А если HTTP-проверка получает по адресу веб-страницу, а фронтенда с этим доменом в проекте нет, появляется шаг «На app.example.com не подключён фронтенд»: ссылка из него открывает добавление фронтенда с уже вписанным доменом.
Что делает ИИ-ассистент
Через MCP ассистент создаёт фронтенд в проекте, получает ключ и вписывает пакет, init и ErrorBoundary в код вашего приложения, а затем проверяет, что события пошли. Он же разбирает ошибки фронтенда по стеку, сессии и трассе бэкенда, настраивает загрузку source maps и закрывает ошибку после выкладки исправления.
Что дальше
- Source maps и релизы — стек по исходному коду вместо минифицированного бандла.
- Сессии и пользователи — что делал посетитель перед ошибкой и кого она задела.
- Запросы из браузера и трасса бэкенда — из ошибки фронтенда в причину на сервере.
- ErrorBoundary — как ловить падения компонентов React.
Первый сервер или стек подключается за пару минут. Бесплатно в раннем доступе.
Нашли неточность или не хватает ответа? Напишите в поддержку