Component request: `ErrorBoundary`

[awhobbs87]

Overview

Request to add an ErrorBoundary component to Kumo. The CONTRIBUTING.md guidance suggests opening an issue first for non-trivial additions, so this is a proposal: please push back on shape / scope / whether this belongs in Kumo at all before any code lands.

Motivation

Every app that consumes Kumo ends up writing its own error boundary, because React doesn't ship one and Kumo doesn't either. They tend to look very similar:

• A class component (still the only way to do getDerivedStateFromError / componentDidCatch).
• A default fallback UI with a warning icon, a title, the error message in a <pre>, and a "Try again" button.
• A name prop so the caller can label which boundary tripped, both for the fallback heading and for the console log.
• Optional render-prop fallback for callers who want their own UI: fallback?: (error, reset) => ReactNode.

The bit that differs in production-grade implementations is error classification + a smarter reset behaviour:

• Hook-order violations (Rendered fewer hooks than expected, Rules of Hooks) - log a specific Rules-of-Hooks pointer in addition to the regular stack, because retrying re-renders the same broken code path. These are always bugs, not transient failures.
• Chunk-loading failures (Failed to fetch dynamically imported module, Loading chunk N failed, Vite-HMR MIME mismatch errors) - the broken module will keep throwing on retry, so "Try again" should force a full page reload (window.location.reload()) instead of clearing the error state.
• Generic render errors - the default "Try again" that clears state and re-renders the subtree.

I have a working implementation of all of the above in an internal Cloudflare app. It's ~170 lines including the fallback UI and error-classifier regexes. Happy to port it to Kumo's conventions (compound component pattern if appropriate, semantic color tokens instead of raw Tailwind, cn(), displayName, JSDoc, KUMO_*_VARIANTS, etc.).

Proposed API

import { ErrorBoundary } from "@cloudflare/kumo";

// Default fallback UI (warning icon + title + error message + Try again button)
<ErrorBoundary name="Sidebar">
  <AppSidebar />
</ErrorBoundary>

// Custom fallback via render prop
<ErrorBoundary
  name="Dashboard"
  fallback={(error, reset) => (
    <div>
      <p>{error.message}</p>
      <Button onClick={reset}>Retry</Button>
    </div>
  )}
>
  <Dashboard />
</ErrorBoundary>

Props

• children: ReactNode - required, the subtree to wrap.
• name?: string - optional label, shown in the fallback heading (Something went wrong in {name}) and prefixed to console logs. Helps diagnose which boundary tripped when several are nested.
• fallback?: (error: Error, reset: () => void) => ReactNode - optional render prop. When provided, fully replaces the default fallback UI.
• onError?: (error: Error, info: ErrorInfo) => void - optional callback for telemetry pipelines (Sentry, Datadog, etc.). Fires from componentDidCatch.

Behaviour

• Default fallback uses role="alert" so screen readers announce errors when they appear.
• Error classification runs against error.message to bucket into hooks | chunk | generic. The bucket is used to:
  • Tailor the fallback title and message (hook violations get a Rules-of-Hooks pointer).
  • Decide whether reset() clears state (generic / hooks) or reloads the page (chunk).
• Console logging is always-on, even in production (errors caught by boundaries are real bugs, not noise; suppressing them in prod hurts debugging when you're staring at a Sentry alert and want the stack trace in the user's DevTools).

Why this fits Kumo

• It's a primitive that every consuming app needs.
• The default fallback styling (border, padding, typography, button) should match Kumo's design language - which means the right place for it is in Kumo, not duplicated by every consumer.
• It's framework-agnostic (no React Router / Next.js dependency), so it lives well inside @cloudflare/kumo.

Why this might NOT belong in Kumo

A few reasons to push back, and how I'd respond:

1. "It's not a UI primitive, it's app infrastructure." The render-prop API + onError + name shape is infrastructure-flavoured, fair. But the default fallback's visual identity is purely Kumo's job, and bundling the two avoids each consumer reinventing the styling.
2. "react-error-boundary already exists." It does, and it's good. But (a) it doesn't ship classification, and (b) it doesn't ship a Kumo-styled fallback. We could depend on it under the hood and provide the styled fallback + classifier on top, which would shrink the maintenance surface inside Kumo. Happy to take that direction if maintainers prefer.
3. "Putting Kumo's design language on an error fallback is a footgun for prod." Real concern. Counter: the alternative is each consumer building their own, which is what causes the inconsistency this issue is trying to fix.

What I'd like from this issue

1. Yes / no on the principle: should this live in Kumo at all? If no, close and I'll keep the implementation app-side.
2. API shape feedback: are the four props the right surface? Should onError be there from day one or added later? Should fallback get errorKind (the classification result) as a third arg so custom fallbacks can also branch on it?
3. Implementation direction: roll our own ~170-line class component, or depend on react-error-boundary and layer the classifier + styled fallback on top?

Once the shape is settled, I'll open a PR.

Reference implementation

From the internal reference implementation. The classification regexes:

const HOOKS_PATTERN =
  /rendered (more|fewer) hooks|change in the order of hooks|hooks can only be called/i;
const CHUNK_PATTERN =
  /requested module.*MIME|failed to fetch dynamically imported|loading chunk|dynamically imported module/i;

Reset behaviour:

reset = () => {
  if (this.state.errorKind === "chunk") {
    window.location.reload();
    return;
  }
  this.setState({ hasError: false, error: null, errorKind: null });
};

I'd port the regex-driven classifier as-is, and we can refine the patterns over time as new error shapes show up. The classification doesn't need to be perfect - the buckets are about reset semantics (retry vs reload), and "generic" is a fine fallback when nothing matches.

[awhobbs87]

Update: narrowing this to a presentational-only proposal

Coming back to my own issue after living with the full implementation in our app for a while. I think the original proposal bundled two things that don't belong together, and the infrastructure half is exactly what objection #1 ("it's not a UI primitive, it's app infrastructure") is right about. So I'd like to pivot.

The split

The original ErrorBoundary request mixes:

1. App infrastructure that I no longer think belongs in Kumo: the class component, getDerivedStateFromError / componentDidCatch, the error-classification regexes (hooks / chunk / generic), the reset-vs-reload semantics, and the onError telemetry hook. These are genuinely app-side concerns. Classification buckets and reset behaviour differ per app, and they tie the component to a lifecycle that has nothing to do with Kumo's design language.

2. A pure presentational surface that very much is Kumo's job: the styled fallback card (icon, title, message, optional diagnostics, action button), with semantic tokens, light/dark parity, and role="alert".

Only (2) belongs in Kumo. So instead of ErrorBoundary, I'd propose a presentational ErrorState component, and let each app keep its own boundary class that renders it.

This sidesteps all three "why this might NOT belong" objections from the original post:

• "It's not a UI primitive." Now it is one. No class component, no lifecycle, no classification.
• "react-error-boundary already exists." Unaffected: apps keep using their own boundary (or react-error-boundary) and render ErrorState from the fallback.
• "Design language on a prod error screen is a footgun." ErrorState is opt-in presentation; the app decides when and what to render, including whether to show raw details (we gate ours to DEV).

Proposed API

import { ErrorState } from "@cloudflare/kumo";

<ErrorState
  severity="error"            // "error" | "warning": drives icon medallion tint
  title="Something went wrong"
  description="An unexpected error occurred. Try again, or reload the page."
  details={import.meta.env.DEV ? error.message : undefined} // optional, collapsible
  actionLabel="Try again"
  onAction={reset}
/>

Prop	Type	Notes
title	string	Required heading.
description	string	Required one-line explanation.
severity	"error" | "warning"	Optional, defaults "error". Drives the icon medallion tint + accent.
actionLabel + onAction	string + () => void	Optional recovery action. Rendered only when both are present.
details	string	Optional raw diagnostic. Rendered in a collapsed, monospaced disclosure.
icon	ReactNode	Optional icon override.
className	string	Optional.

No children, no name, no fallback render prop, no onError: those were all boundary concerns and they leave with the boundary.

Proof of concept

I extracted exactly this out of our app's boundary (the boundary kept all the classification/reset/logging; it now just feeds props into ErrorState). Screenshots of the presentational component rendered in isolation, both themes:

Generic / warning severity (light + dark)

Hook violation / error severity (light + dark)

Chunk-load (different action label) + the collapsible diagnostics block expanded

Narrowed questions for maintainers

1. Yes / no on ErrorState as a presentational primitive? This is the part I'm now confident belongs in Kumo.
2. Severity surface: is "error" | "warning" the right set, or do you want an "info" tone too (for non-error empty/blocked states that could reuse the same shell)?
3. Diagnostics disclosure: keep the collapsible details in-component, or leave that to consumers and ship only title/description/action?
4. Naming: ErrorState vs ErrorFallback. I lean ErrorState since it's deliberately not a boundary, but happy to follow your convention if there's a sibling EmptyState-style family.

If the principle lands, I'll open a PR for ErrorState only and keep the boundary + classifier in our app where they belong.

[awhobbs87]

Generic error, light mode

Generic error, dark mode

Hook violation (error severity), light mode

Hook violation (error severity), dark mode

Chunk-load error with "Reload page" action, light mode

Chunk-load error with "Reload page" action, dark mode

Diagnostics disclosure expanded, light mode

Diagnostics disclosure expanded, dark mode