Error Boundary Kit

npm install vue-error-boundary-kit@latest

01 — Назначение

Когда это пригодится

Один необработанный throw в глубине дерева компонентов — и всё приложение превращается в белый экран у пользователя; vue-error-boundary-kit ограничивает область поражения одним виджетом вместо всей страницы.

Один упавший виджет не должен ронять всю страницу

Карточка товара, блок комментариев или виджет на дашборде оборачивается в собственную защитную границу — если он падает, соседние блоки продолжают работать, а не превращаются в тот же белый экран.

Ошибка происходит не в рендере, а в обработчике

Обычный перехват ошибок в компонентах не видит исключения из обработчиков кликов, таймеров или необработанные отклонения промисов — для них нужен отдельный, глобальный перехват.

Не все ошибки одинаково критичны

Сетевой запрос стоит повторить с задержкой, а ошибку в самой логике — сразу показать пользователю и остановиться. Границу можно настроить так, чтобы она сама различала эти два случая и не пыталась бессмысленно повторить то, что повторять не стоит.

Ошибки нужно видеть не только в консоли

Подключаемые адаптеры отправляют ошибки в Sentry, Bugsnag или свой HTTP-эндпоинт, а встроенная история в DevTools показывает, что упало, ещё до жалобы пользователя в поддержку.

02 — Фичи

Коротко о главном

Декларативный компонент ErrorBoundary

Оборачивайте любую часть приложения в <ErrorBoundary> с fallback-слотом для отображения ошибки. Управляйте состоянием через resetKeys, maxRetries, автоматический сброс при изменении пропсов. Получайте доступ к ошибке, методам reset/retry и счётчику попыток как в слоте, так и через ref.

Программный перехват и глобальный мониторинг

Используйте useErrorBoundary() для ручной регистрации ошибок из любого кода — например, при парсинге JSON или в обработчиках событий. А с помощью useGlobalErrorCapture() перехватывайте необработанные ошибки и отклонённые промисы, которые Vue не видит.

Гибкая система репортинга с адаптерами

Отправляйте ошибки в Sentry, Bugsnag, LogRocket, HTTP endpoint или консоль через подключаемые адаптеры. Каждый адаптер поставляется отдельным entry point, не раздувая основной бандл. Встроенные rate-limiting и breadcrumbs защищают от спама и дают контекст.

Готовая интеграция с Nuxt, vue-router и TanStack Query

Nuxt-модуль автоматически регистрирует компонент и утилиты. useNuxtErrorBoundary() перехватывает ошибки на уровне приложения, а useRouterErrorBoundary() — ошибки навигации и асинхронных роутов. Для TanStack Query есть хук сброса ошибочных запросов.

AsyncBoundary, история ошибок и SSR-безопасность

AsyncBoundary объединяет Suspense и ErrorBoundary с единым API и слотами loading/fallback. Для отладки используйте историю ошибок и панель в devtools. Все компоненты безопасны для SSR — ошибки рендеринга не роняют сервер, а гидратация всегда сходится к корректному состоянию.

Точная фильтрация ошибок и повтор с задержкой

Указывайте shouldCatch, чтобы граница перехватывала только нужные типы ошибок, пробрасывая остальные выше по дереву — это позволяет расставлять вложенные границы с разной зоной ответственности. Автоматический retry с экспоненциальной задержкой сам повторяет операцию после сбоя.

03 — Быстрый пример

Как это работает

Декларативная граница ошибок

Оборачиваете часть дерева в <ErrorBoundary> — при падении рендерится fallback-слот, а resetKeys сбрасывает границу автоматически при смене роута.

App.vue
<script setup lang="ts">
import { ErrorBoundary } from 'vue-error-boundary-kit'
import UserProfile from './UserProfile.vue'

const userId = ref('42')
const routeId = ref('profile')

function handleError(error) {
  // error: CapturedError — see Types below
}
</script>

<template>
  <ErrorBoundary :reset-keys="[routeId]" @error="handleError">
    <template #default>
      <UserProfile :id="userId" />
    </template>
    <template #fallback="{ error, reset, retryCount }">
      <ErrorState :message="error.message" @retry="reset" />
    </template>
  </ErrorBoundary>
</template>

Ручной перехват вне шаблона

useErrorBoundary() ловит то, что errorCaptured в принципе не видит — например, ошибку в обработчике события или при разборе непроверенных данных.

manual-capture.ts
import { useErrorBoundary } from 'vue-error-boundary-kit'

const { error, hasError, reset, captureError } = useErrorBoundary({
  onError: (e) => report(e),
  reporter: myReporter,
})

try {
  JSON.parse(untrustedInput)
} catch (err) {
  captureError(err, { source: 'manual', componentName: 'ImportPanel' })
}

Защита от шторма одинаковых ошибок в Sentry

createRateLimitedReporter оборачивает любые репортеры и сам режет дубликаты и всплеск отчётов — сломанный список, который перерендеривается сотни раз в секунду, не завалит Sentry одинаковыми событиями.

reporting.ts
import { createSentryReporter } from 'vue-error-boundary-kit/adapters/sentry'
import { createRateLimitedReporter } from 'vue-error-boundary-kit/adapters/rate-limit'

const sentryReporter = createSentryReporter({ client: sentryClient })

const reporter = createRateLimitedReporter([sentryReporter], {
  maxPerWindow: 10, // at most 10 reports forwarded per 10s window
  dedupWindowMs: 10_000, // suppress identical repeats within this window
})

// Pass `reporter` to <ErrorBoundary>, useErrorBoundary(), or
// useGlobalErrorCapture() — it composes with everything else, same as any
// other ErrorReporter.

Начать знакомство →