Patterns

Error Boundaries

Three layers of error isolation prevent cascading failures. A crashing chart never takes down the whole page. This is mandatory in every Mukoko app.

Layer overview

Component

Wraps individual component previews. Shows a minimal fallback if a single component fails to render.

components/error-boundary.tsx

Section

Wraps page sections (Layer 4). Shows section name, retry button, and logs to observability. Other sections continue working.

components/section-error-boundary.tsx

Route / Global

Last-resort boundaries. Route-level catches page errors with reset. Global catches the entire app with hardcoded styles.

app/error.tsx + app/global-error.tsx

Live demonstration

Click each button to trigger an error in different components. Watch how the error is contained to just that boundary — everything else continues working.

Component ErrorBoundary

Card AActive

This component is working normally.

Card BActive

This component is working normally.

Card CActive

This component is working normally.

Each card is wrapped in an ErrorBoundary. Crashing one shows a minimal fallback — the others are unaffected.

SectionErrorBoundary

Weather Data Section

Full section with retry capability and named error display.

Community Reports Section

Independent section — survives if Weather Data crashes.

SectionErrorBoundary shows the section name, a retry button, and logs the error via the observability system. Click "Try again" to recover.

1. Component ErrorBoundary

The simplest boundary. Wraps individual components (like preview cards) and shows a minimal fallback. No retry — the component is simply replaced with a “failed to render” message.

components/error-boundary.tsx


import { ErrorBoundary } from "@/components/error-boundary"
 
// In a component showcase or preview
<ErrorBoundary
  fallback={<p className="text-xs text-muted-foreground">Preview unavailable</p>}
>
  <ChartPreview />
</ErrorBoundary>

2. SectionErrorBoundary

The workhorse boundary for the 5-layer architecture. Every page section gets one. Shows the section name, a retry button, and logs errors via the observability system. Supports custom fallback UI and an onError callback for external reporting.

components/section-error-boundary.tsx


import { SectionErrorBoundary } from "@/components/section-error-boundary"
 
<main className="flex flex-col gap-6">
  <SectionErrorBoundary section="Weather Overview">
    <WeatherOverview />
  </SectionErrorBoundary>
 
  <SectionErrorBoundary section="Activity Feed">
    <ActivityFeed />
  </SectionErrorBoundary>
 
  <SectionErrorBoundary
    section="Analytics"
    onError={(error, section) => {
      // Report to external service
      reportError(error, { section })
    }}
  >
    <AnalyticsChart />
  </SectionErrorBoundary>
</main>

Props

Prop	Type	Description
`section`	`string`	Section name for logging and fallback display
`fallback?`	`ReactNode`	Custom fallback UI (default: card with retry)
`onError?`	`(error, section) => void`	Callback for external error reporting
`className?`	`string`	Additional styles for the fallback container

3. Route + Global Error Boundaries

Next.js provides these automatically. The route-level boundary (error.tsx) catches errors within a route segment and offers a retry. The global boundary (global-error.tsx) is the absolute last resort — it wraps the entire HTML document with hardcoded colors since CSS custom properties may not be available.

app/error.tsx


"use client"
 
export default function Error({ error, reset }) {
  return (
    <div className="flex min-h-screen items-center
      justify-center bg-background">
      <div className="flex flex-col items-center gap-6">
        <h1>Something went wrong</h1>
        {error.digest && (
          <p className="font-mono text-xs">
            Error ID: {error.digest}
          </p>
        )}
        <Button onClick={reset}>Try again</Button>
        <Button variant="outline" asChild>
          <a href="/">Go home</a>
        </Button>
      </div>
    </div>
  )
}

app/global-error.tsx


"use client"
 
// Hardcoded colors — CSS custom
// properties may not be available
export default function GlobalError({
  error,
  reset,
}) {
  return (
    <html lang="en">
      <body className="bg-[#0A0A0A]
        text-[#F5F5F4]">
        <div className="flex min-h-screen
          items-center justify-center">
          <h1>Something went wrong</h1>
          <button onClick={reset}>
            Try again
          </button>
        </div>
      </body>
    </html>
  )
}

Install from registry


# SectionErrorBoundary (recommended for page sections)
npx shadcn@latest add https://registry.mukoko.com/api/v1/ui/section-error-boundary
 
# Basic ErrorBoundary (for component previews)
npx shadcn@latest add https://registry.mukoko.com/api/v1/ui/error-boundary