@molecule/app-root-error-boundary-react

Top-level React error boundary that catches render errors, logs them via the bonded @molecule/app-logger, and shows a minimal localized fallback message through @molecule/app-i18n.

Exports <RootErrorBoundary> (class component; children is the only prop). Mount it directly under your routing root so it covers the whole route tree.

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Quick Start

import type { ReactNode } from 'react'

import { RootErrorBoundary } from '@molecule/app-root-error-boundary-react'

function AppRoot({ children }: { children: ReactNode }) {
  return <RootErrorBoundary>{children}</RootErrorBoundary>
}

Type

feature

Installation

npm install @molecule/app-root-error-boundary-react @molecule/app-i18n @molecule/app-logger @molecule/app-ui react
npm install -D @types/react

API

Classes

RootErrorBoundary

Top-level React error boundary that catches render errors, logs them via the bonded @molecule/app-logger, and falls back to a minimal recovery surface localized through @molecule/app-i18n.

Use this directly under your routing root so it covers the whole route tree.

class RootErrorBoundary extends Component<Props, State> {
  override state: State = { hasError: false }

  /**
   * Transitions the component into error state when a render error is caught.
   */
  static getDerivedStateFromError(): State {
    return { hasError: true }
  }

  /**
   * Logs the caught render error and its component stack via the bonded logger.
   */
  override componentDidCatch(err: Error, info: ErrorInfo): void {
    logError(err, info.componentStack ?? '')
  }

  /**
   * Renders children normally, or a localized fallback UI when an error has been caught.
   */
  override render(): ReactNode {
    if (this.state.hasError) {
      const cm = getClassMap()
      return (
        <div
          className={cm.cn(
            cm.flex({ direction: 'col', align: 'center', justify: 'center' }),
            cm.sp('p', 8),
          )}
          role="alert"
        >
          <p className={cm.cn(cm.textSize('sm'), cm.fontWeight('medium'))}>
            {t('error.unknown', {}, { defaultValue: 'An unexpected error occurred.' })}
          </p>
        </div>
      )
    }
    return this.props.children
  }
}

Injection Notes

Requirements

Peer dependencies:

• @molecule/app-i18n ^1.0.1
• @molecule/app-logger ^1.0.1
• @molecule/app-ui ^1.0.1
• react ^18.0.0 || ^19.0.0

Runtime Dependencies

• @molecule/app-i18n

• @molecule/app-logger

• @molecule/app-ui

• react

• The fallback UI styles itself via getClassMap() — if no ClassMap is bonded the boundary itself throws while rendering the fallback. Ensure setClassMap() runs during bootstrap, before anything can error.

• There is no retry/reload action — the fallback is a static message (key error.unknown). Wrap or fork when you need a recovery button.

• React error boundaries catch RENDER errors only — not event handlers, async code, or server-side rendering errors.

• Uses the core t() from @molecule/app-i18n (not the React hook), so no I18nProvider is required; without locale registration it falls back to English. Translations: @molecule/app-locales-root-error-boundary.

Translations

Translation strings are provided by @molecule/app-locales-root-error-boundary.