Мониторинг ошибок фронтенда на 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 или новее:

bash
npm i @nablops/react

В точке входа (src/main.tsx у Vite) — до рендера приложения:

tsx
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

tsx
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:

ts
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 и закрывает ошибку после выкладки исправления.

Что дальше

Попробуйте NablOps

Первый сервер или стек подключается за пару минут. Бесплатно в раннем доступе.

Создать аккаунт

Нашли неточность или не хватает ответа? Напишите в поддержку