ErrorBoundary

Workbench 불러오는 중…

Component intent의도와 경계 읽기

자식 트리의 렌더 도중 발생한 throw 를 잡아 트리 전체 white-out 대신 복구 가능한 fallback 을 보여주는 class 컴포넌트. 기본 fallback 은 잡은 error 를 humanizeApiError 로 {title, detail} 로 변환해 Callout(variant="danger") + '다시 시도' Button 으로 렌더한다(한국어 사용자 메시지). fallback prop 으로 직접 렌더를 대체하고, onError 로 Sentry/console/datadog 로깅을 붙이며, resetKeys 원소가 바뀌면(예 pathname·query·userId) 자동으로 reset 된다. getDerivedStateFromError/componentDidCatch 는 hooks 로 대체 불가라 class + "use client" 로 구현.

01기본 (로깅 + 라우트 기준 자동 복구)tsxfragment

import { ErrorBoundary } from "@axe/ui";import { usePathname } from "next/navigation";function Page({ children }: { children: React.ReactNode }) {  const pathname = usePathname();  return (    <ErrorBoundary      resetKeys={[pathname]}      onError={(error, info) => reportToSentry(error, info)}    >      {children}    </ErrorBoundary>  );}

02custom fallbacktsxfragment

import { ErrorBoundary } from "@axe/ui";<ErrorBoundary  fallback={(error, reset) => (    <div role="alert">      <p>차트를 그리지 못했어요: {error.message}</p>      <button onClick={reset}>다시 시도</button>    </div>  )}>  <StreamingChart /></ErrorBoundary>

이름	타입	필수	기본값	설명
`children`	`React.ReactNode`	필수	—	감쌀 트리. 이 안의 렌더 throw 만 포착된다.
`fallback`	`(error: Error, reset: () => void) => React.ReactNode`	—	—	받으면 기본 Callout fallback 을 대체. reset 을 호출하면 boundary 가 복구.
`onError`	`(error: Error, errorInfo: React.ErrorInfo) => void`	—	—	외부 로깅 hook — componentDidCatch 에서 호출(Sentry/console/datadog).
`resetKeys`	`unknown[]`	—	—	원소 중 하나라도 Object.is 로 바뀌면 자동 reset(라우트/쿼리 변경 패턴).

클래스	안정성	용도
`.axe-error-boundary`	stable	기본 fallback wrapper(spacing 컬럼). custom fallback 시엔 렌더 안 됨.
`.axe-error-boundary__detail`	internal	humanizeApiError 의 detail 문단(기본 fallback 내부).
`.axe-error-boundary__actions`	internal	'다시 시도' 액션 row(기본 fallback 내부).

비-React 소비 노트

에러 포착·복구는 순수 React 로직이라 CSS-only 로 소비할 수 없다. .axe-error-boundary* 클래스는 기본 fallback 의 얇은 스킨일 뿐이며, custom fallback 을 넘기면 전혀 렌더되지 않는다. 시각을 바꾸려면 fallback prop 으로 직접 렌더하는 편이 정석.

권장

LLM 응답·streaming·외부 tool 결과처럼 render throw 가능성이 높은 island 를 개별로 감싸 격리한다.
resetKeys 에 pathname·query·userId 등을 넣어 새 입력 시 자동 복구되게 한다.
onError 로 반드시 로깅을 붙여 삼켜진 에러가 관측 가능하게 한다.

지양

이벤트 핸들러·비동기 코드의 에러를 잡을 거라 기대하지 말 것(그건 try/catch 몫 — 경계 밖).
앱 최상단 하나만 두지 말 것 — 한 곳이 터지면 전체가 white-out 되므로 경계를 잘게 나눈다.

먼저 보고, 그다음 계약을 읽습니다

예제

Props

.axe-* 클래스 계약

권장 · 지양