Error Boundary

An enhanced React Error Boundary that captures breadcrumbs (actions leading to the error), generates fingerprints for grouping, and provides beautiful development-mode error UI.

Quick Setup

Wrap your application with the error boundary:

typescript

1// app/layout.tsx
2import { EnhancedErrorBoundary } from '@vestig/next/error'
3 
4export default function RootLayout({ children }: { children: React.ReactNode }) {
5  return (
6    <html>
7      <body>
8        <EnhancedErrorBoundary
9          onError={(err) => console.error('Error caught:', err)}
10        >
11          {children}
12        </EnhancedErrorBoundary>
13      </body>
14    </html>
15  )
16}

Configuration

Prop	Type	Default	Description
`fallback`	`ReactNode \| ((error: EnhancedError) => ReactNode)`	Built-in UI	Custom error UI
`onError`	`(error: EnhancedError) => void`	`undefined`	Callback when error is caught
`maxBreadcrumbs`	`number`	`50`	Maximum breadcrumbs to store
`showBreadcrumbs`	`boolean`	`true`	Show breadcrumbs in dev UI
`reportEndpoint`	`string`	`undefined`	POST endpoint for error reporting

Breadcrumbs

Breadcrumbs capture user actions leading up to an error, providing context for debugging.

Automatic Tracking

Enable automatic click and fetch tracking:

typescript

1'use client'
2 
3import { useEffect } from 'react'
4import { setupClickTracking, setupFetchTracking } from '@vestig/next/error'
5 
6export function BreadcrumbTracker() {
7  useEffect(() => {
8    const cleanupClick = setupClickTracking()
9    const cleanupFetch = setupFetchTracking()
10 
11    return () => {
12      cleanupClick()
13      cleanupFetch()
14    }
15  }, [])
16 
17  return null
18}

Manual Breadcrumbs

Add custom breadcrumbs for important actions:

typescript

1import {
2  addNavigationBreadcrumb,
3  addClickBreadcrumb,
4  addInputBreadcrumb,
5  addFetchBreadcrumb,
6  addErrorBreadcrumb,
7  addCustomBreadcrumb,
8} from '@vestig/next/error'
9 
10// Navigation
11addNavigationBreadcrumb('/dashboard', '/settings')
12 
13// User click
14addClickBreadcrumb('Submit button', 'button#submit')
15 
16// Form input (automatically redacts sensitive fields)
17addInputBreadcrumb('email', 'user@example.com', 'input#email')
18addInputBreadcrumb('password', '***', 'input#password')  // Redacted
19 
20// API call
21addFetchBreadcrumb('GET', '/api/users', 200, 150)
22 
23// Non-fatal error
24addErrorBreadcrumb('Failed to load preferences', error)
25 
26// Custom event
27addCustomBreadcrumb('Feature flag enabled', { flag: 'dark-mode' })

Breadcrumb Categories

Category	Icon	Description
`log`	📝	Log messages
`navigation`	🧭	Route changes
`click`	👆	User clicks
`input`	⌨️	Form inputs
`fetch`	🌐	API calls
`error`	❌	Previous errors
`custom`	📌	Custom events

Error Fingerprinting

Fingerprints group similar errors together, useful for error aggregation:

typescript

1import { generateFingerprint, isSameError, groupErrors } from '@vestig/next/error'
2 
3// Generate fingerprint from error
4const fingerprint = generateFingerprint(error, stackFrames)
5// 'a1b2c3d4'
6 
7// Compare errors
8const same = isSameError(error1, error2)
9 
10// Group multiple errors
11const grouped = groupErrors(errors)
12// Map<fingerprint, errors[]>

Fingerprints are based on:

Error type/name
Normalized error message (UUIDs, IDs, URLs removed)
Top stack frames (focusing on app code)

Stack Trace Parsing

Parse and format stack traces from any browser:

typescript

1import {
2  parseStackTrace,
3  parseComponentStack,
4  getMostRelevantFrame,
5} from '@vestig/next/error'
6 
7// Parse error stack
8const frames = parseStackTrace(error.stack)
9// [{ fileName, lineNumber, columnNumber, functionName, isAppCode }, ...]
10 
11// Get React component tree
12const components = parseComponentStack(errorInfo.componentStack)
13// ['App', 'Layout', 'Page', 'BuggyComponent']
14 
15// Find the most relevant frame (your code, not node_modules)
16const frame = getMostRelevantFrame(frames)

Enhanced Error Object

When an error is caught, the callback receives an enhanced error object:

typescript

1interface EnhancedError {
2  error: Error                    // Original error
3  fingerprint: string             // For grouping
4  frames: StackFrame[]            // Parsed stack
5  componentStack?: string         // React tree
6  breadcrumbs: Breadcrumb[]       // Actions before crash
7  timestamp: string               // ISO timestamp
8  environment: {
9    userAgent: string
10    url: string
11    pathname: string
12  }
13}

Custom Fallback UI

Provide your own error UI:

typescript

1<EnhancedErrorBoundary
2  fallback={(error) => (
3    <div className="error-page">
4      <h1>Something went wrong</h1>
5      <p>Error ID: {error.fingerprint}</p>
6      <button onClick={() => window.location.reload()}>
7        Try Again
8      </button>
9    </div>
10  )}
11>
12  {children}
13</EnhancedErrorBoundary>

Error Reporting

Send errors to your backend:

typescript

1<EnhancedErrorBoundary
2  reportEndpoint="/api/errors"
3  onError={(err) => {
4    // Also send to Sentry, LogRocket, etc.
5    Sentry.captureException(err.error, {
6      fingerprint: [err.fingerprint],
7      contexts: {
8        breadcrumbs: err.breadcrumbs,
9      },
10    })
11  }}
12>
13  {children}
14</EnhancedErrorBoundary>

Error API Endpoint

typescript

1// app/api/errors/route.ts
2import { NextRequest, NextResponse } from 'next/server'
3 
4export async function POST(request: NextRequest) {
5  const error = await request.json()
6 
7  // Log to your error tracking service
8  await logError({
9    fingerprint: error.fingerprint,
10    message: error.error.message,
11    stack: error.error.stack,
12    breadcrumbs: error.breadcrumbs,
13    timestamp: error.timestamp,
14  })
15 
16  return NextResponse.json({ received: true })
17}

Development vs Production

Feature	Development	Production
Error UI	Rich overlay with stack	Simple "Something went wrong"
Breadcrumbs	Shown in overlay	Sent to `reportEndpoint`
Source Maps	Applied to stack	Use sourcemap service
Component Tree	Shown	Hidden

Best Practices

1. Track Critical User Actions

Add breadcrumbs at key points in your app:

typescript

1// Before important operations
2addCustomBreadcrumb('Starting checkout', { items: cart.length })
3 
4// After API calls
5addFetchBreadcrumb('POST', '/api/checkout', response.status, duration)

2. Use Multiple Boundaries

Wrap different sections for granular error handling:

typescript

1<EnhancedErrorBoundary fallback={<DashboardError />}>
2  <Dashboard />
3</EnhancedErrorBoundary>
4 
5<EnhancedErrorBoundary fallback={<SidebarError />}>
6  <Sidebar />
7</EnhancedErrorBoundary>

3. Combine with Logging

Log errors along with catching them:

typescript

1import { createLogger } from 'vestig'
2 
3const log = createLogger({ namespace: 'errors' })
4 
5<EnhancedErrorBoundary
6  onError={(err) => {
7    log.error('Unhandled error', {
8      fingerprint: err.fingerprint,
9      breadcrumbs: err.breadcrumbs.length,
10    })
11  }}
12>

Next Steps

Dev Overlay — See breadcrumbs in real-time
Logging Basics — Log errors properly
Error Handling — Error serialization

Error Boundary

An enhanced React Error Boundary that captures breadcrumbs (actions leading to the error), generates fingerprints for grouping, and provides beautiful development-mode error UI.

Quick Setup

Wrap your application with the error boundary:

typescript

1// app/layout.tsx
2import { EnhancedErrorBoundary } from '@vestig/next/error'
3 
4export default function RootLayout({ children }: { children: React.ReactNode }) {
5  return (
6    <html>
7      <body>
8        <EnhancedErrorBoundary
9          onError={(err) => console.error('Error caught:', err)}
10        >
11          {children}
12        </EnhancedErrorBoundary>
13      </body>
14    </html>
15  )
16}

Configuration

Prop	Type	Default	Description
`fallback`	`ReactNode \| ((error: EnhancedError) => ReactNode)`	Built-in UI	Custom error UI
`onError`	`(error: EnhancedError) => void`	`undefined`	Callback when error is caught
`maxBreadcrumbs`	`number`	`50`	Maximum breadcrumbs to store
`showBreadcrumbs`	`boolean`	`true`	Show breadcrumbs in dev UI
`reportEndpoint`	`string`	`undefined`	POST endpoint for error reporting

Breadcrumbs

Breadcrumbs capture user actions leading up to an error, providing context for debugging.

Automatic Tracking

Enable automatic click and fetch tracking:

typescript

1'use client'
2 
3import { useEffect } from 'react'
4import { setupClickTracking, setupFetchTracking } from '@vestig/next/error'
5 
6export function BreadcrumbTracker() {
7  useEffect(() => {
8    const cleanupClick = setupClickTracking()
9    const cleanupFetch = setupFetchTracking()
10 
11    return () => {
12      cleanupClick()
13      cleanupFetch()
14    }
15  }, [])
16 
17  return null
18}

Manual Breadcrumbs

Add custom breadcrumbs for important actions:

typescript

1import {
2  addNavigationBreadcrumb,
3  addClickBreadcrumb,
4  addInputBreadcrumb,
5  addFetchBreadcrumb,
6  addErrorBreadcrumb,
7  addCustomBreadcrumb,
8} from '@vestig/next/error'
9 
10// Navigation
11addNavigationBreadcrumb('/dashboard', '/settings')
12 
13// User click
14addClickBreadcrumb('Submit button', 'button#submit')
15 
16// Form input (automatically redacts sensitive fields)
17addInputBreadcrumb('email', 'user@example.com', 'input#email')
18addInputBreadcrumb('password', '***', 'input#password')  // Redacted
19 
20// API call
21addFetchBreadcrumb('GET', '/api/users', 200, 150)
22 
23// Non-fatal error
24addErrorBreadcrumb('Failed to load preferences', error)
25 
26// Custom event
27addCustomBreadcrumb('Feature flag enabled', { flag: 'dark-mode' })

Breadcrumb Categories

Category	Icon	Description
`log`	📝	Log messages
`navigation`	🧭	Route changes
`click`	👆	User clicks
`input`	⌨️	Form inputs
`fetch`	🌐	API calls
`error`	❌	Previous errors
`custom`	📌	Custom events

Error Fingerprinting

Fingerprints group similar errors together, useful for error aggregation:

typescript

1import { generateFingerprint, isSameError, groupErrors } from '@vestig/next/error'
2 
3// Generate fingerprint from error
4const fingerprint = generateFingerprint(error, stackFrames)
5// 'a1b2c3d4'
6 
7// Compare errors
8const same = isSameError(error1, error2)
9 
10// Group multiple errors
11const grouped = groupErrors(errors)
12// Map<fingerprint, errors[]>

Fingerprints are based on:

Error type/name
Normalized error message (UUIDs, IDs, URLs removed)
Top stack frames (focusing on app code)

Stack Trace Parsing

Parse and format stack traces from any browser:

typescript

1import {
2  parseStackTrace,
3  parseComponentStack,
4  getMostRelevantFrame,
5} from '@vestig/next/error'
6 
7// Parse error stack
8const frames = parseStackTrace(error.stack)
9// [{ fileName, lineNumber, columnNumber, functionName, isAppCode }, ...]
10 
11// Get React component tree
12const components = parseComponentStack(errorInfo.componentStack)
13// ['App', 'Layout', 'Page', 'BuggyComponent']
14 
15// Find the most relevant frame (your code, not node_modules)
16const frame = getMostRelevantFrame(frames)

Enhanced Error Object

When an error is caught, the callback receives an enhanced error object:

typescript

1interface EnhancedError {
2  error: Error                    // Original error
3  fingerprint: string             // For grouping
4  frames: StackFrame[]            // Parsed stack
5  componentStack?: string         // React tree
6  breadcrumbs: Breadcrumb[]       // Actions before crash
7  timestamp: string               // ISO timestamp
8  environment: {
9    userAgent: string
10    url: string
11    pathname: string
12  }
13}

Custom Fallback UI

Provide your own error UI:

typescript

1<EnhancedErrorBoundary
2  fallback={(error) => (
3    <div className="error-page">
4      <h1>Something went wrong</h1>
5      <p>Error ID: {error.fingerprint}</p>
6      <button onClick={() => window.location.reload()}>
7        Try Again
8      </button>
9    </div>
10  )}
11>
12  {children}
13</EnhancedErrorBoundary>

Error Reporting

Send errors to your backend:

typescript

1<EnhancedErrorBoundary
2  reportEndpoint="/api/errors"
3  onError={(err) => {
4    // Also send to Sentry, LogRocket, etc.
5    Sentry.captureException(err.error, {
6      fingerprint: [err.fingerprint],
7      contexts: {
8        breadcrumbs: err.breadcrumbs,
9      },
10    })
11  }}
12>
13  {children}
14</EnhancedErrorBoundary>

Error API Endpoint

typescript

1// app/api/errors/route.ts
2import { NextRequest, NextResponse } from 'next/server'
3 
4export async function POST(request: NextRequest) {
5  const error = await request.json()
6 
7  // Log to your error tracking service
8  await logError({
9    fingerprint: error.fingerprint,
10    message: error.error.message,
11    stack: error.error.stack,
12    breadcrumbs: error.breadcrumbs,
13    timestamp: error.timestamp,
14  })
15 
16  return NextResponse.json({ received: true })
17}

Development vs Production

Feature	Development	Production
Error UI	Rich overlay with stack	Simple "Something went wrong"
Breadcrumbs	Shown in overlay	Sent to `reportEndpoint`
Source Maps	Applied to stack	Use sourcemap service
Component Tree	Shown	Hidden

Best Practices

1. Track Critical User Actions

Add breadcrumbs at key points in your app:

typescript

1// Before important operations
2addCustomBreadcrumb('Starting checkout', { items: cart.length })
3 
4// After API calls
5addFetchBreadcrumb('POST', '/api/checkout', response.status, duration)

2. Use Multiple Boundaries

Wrap different sections for granular error handling:

typescript

1<EnhancedErrorBoundary fallback={<DashboardError />}>
2  <Dashboard />
3</EnhancedErrorBoundary>
4 
5<EnhancedErrorBoundary fallback={<SidebarError />}>
6  <Sidebar />
7</EnhancedErrorBoundary>

3. Combine with Logging

Log errors along with catching them:

typescript

1import { createLogger } from 'vestig'
2 
3const log = createLogger({ namespace: 'errors' })
4 
5<EnhancedErrorBoundary
6  onError={(err) => {
7    log.error('Unhandled error', {
8      fingerprint: err.fingerprint,
9      breadcrumbs: err.breadcrumbs.length,
10    })
11  }}
12>

Next Steps

Dev Overlay — See breadcrumbs in real-time
Logging Basics — Log errors properly
Error Handling — Error serialization