React 교재 · 고급 18편

React Error Boundary — 컴포넌트 에러 격리

한 컴포넌트가 죽었다고 앱 전체가 흰 화면? 그건 1990년대 얘기. Error Boundary 한 번에.

UI 컴포넌트의 깨진 픽셀을 방패가 막아내는 일러스트 — Error Boundary 컨셉

React 의 단점 하나 — 컴포넌트 트리 안 어딘가에서 에러가 throw 되면 전체 화면이 사라진다. 콘솔에 에러 + DOM 비어있음. 사용자 입장에선 "흰 화면" 사고. Error Boundary 가 이 에러를 잡아 격리하고 fallback UI 를 보여준다.

이번 18편은 Error Boundary 의 정확한 동작 + 회사 stack 표준 react-error-boundary 라이브러리 + 17편 TanStack Query 와 결합 + Sentry 같은 에러 추적 통합.

1. Error Boundary 가 잡는 것 / 못 잡는 것

먼저 한계를 알아야. Error Boundary 는 "렌더 중 throw 된 에러" 만 잡는다.

// ✅ 잡힘 — 렌더 중
function Broken() {
  throw new Error('렌더 실패!');
  return <div>...</div>;
}

// ❌ 안 잡힘 — 이벤트 핸들러
function Button() {
  return <button onClick={() => { throw new Error('!') }}>클릭</button>;
}
// 핸들러 안 throw 는 React 가 catch 안 함. try/catch 직접 써야

// ❌ 안 잡힘 — 비동기
useEffect(() => {
  fetch(...).then(() => { throw new Error('!') });  // 직접 catch
}, []);

// ❌ 안 잡힘 — Error Boundary 자기 자신
// ❌ 안 잡힘 — SSR (server-side rendering, Next.js 등)

잡히는 시나리오 — useQuery·useSuspenseQuery 가 throw 하는 에러 (17편 자동 catch), 컴포넌트 본문에서 data.user.name 처럼 null 접근, 잘못된 JSX 반환, render 중 호출한 함수에서 throw — 이 모두 Error Boundary 가 catch.

2. 라이브러리 — react-error-boundary 가 표준

React 공식은 클래스 컴포넌트 + componentDidCatch·getDerivedStateFromError 로 만들라고 했었지만, 함수형 시대에 직접 만들 이유 0. react-error-boundary 가 사실상 표준.

npm install react-error-boundary import { ErrorBoundary } from 'react-error-boundary'; function MyFallback({ error, resetErrorBoundary }) { return ( <div role="alert" className="error-box"> <h2>문제가 발생했어요

핵심 props — FallbackComponent (에러 시 표시), onError (Sentry·DataDog 등 외부 로깅), onReset (재시도 시 정리), resetKeys (이 값이 바뀌면 자동 reset).

3. 배치 전략 — 여러 단계로 격리

Error Boundary 한 개를 최상위에만 두면 — 작은 에러도 화면 전체가 fallback 으로 바뀜. 결제 위젯 에러로 헤더까지 죽는 식. 여러 단계로 중첩해 영향을 격리.

function App() {
  return (
    <ErrorBoundary FallbackComponent={FatalFallback}>
      <Header />
      <Layout>
        <ErrorBoundary FallbackComponent={SidebarFallback}>
          <Sidebar />
        </ErrorBoundary>
        <ErrorBoundary FallbackComponent={MainFallback}>
          <Suspense fallback={<Spinner />}>
            <MainContent />
          </Suspense>
        </ErrorBoundary>
        <ErrorBoundary FallbackComponent={WidgetFallback}>
          <PaymentWidget />
        </ErrorBoundary>
      </Layout>
    </ErrorBoundary>
  );
}

레이어 — ① 최상위 (Fatal): 전체 트리가 죽었을 때만 (rare). ② 페이지 단위: 한 페이지 에러가 다른 페이지에 영향 안 가게. ③ 위젯 단위: 결제·차트·실시간 알림 같은 독립 위젯. 17편 Suspense 와 짝지어 "로딩 → 데이터 도착" 이 안전한 격리.

4. Sentry · 에러 추적 통합

production 에선 에러를 사용자에게만 보여주고 끝나면 안 됨. 개발자가 받아 디버깅 가능해야. Sentry 가 가장 흔한 선택.

npm install @sentry/react // main.tsx import * as Sentry from '@sentry/react'; Sentry.init({ dsn: 'https://[email protected]/...' }); // Error Boundary 안 onError 에서 <ErrorBoundary FallbackComponent={MyFallback} onError={(error, info) => { Sentry.captureException(error, { contexts: { react: { componentStack: info.componentStack } } }); }} >

Sentry 가 자동 수집 — stack trace, 사용자 브라우저·OS, 직전 액션 (breadcrumb), session replay (옵션). 한 사용자가 "에러 났어요" 라고만 알려와도 정확한 컨텍스트 확보.

이벤트 핸들러·비동기 에러도 잡으려면 — useErrorHandler 훅 (react-error-boundary 제공). const handleError = useErrorHandler(); try { ... } catch (e) { handleError(e) } 패턴으로 강제로 boundary 까지 전달. 17편 useQuery 는 자동으로 boundary 까지 throw 해서 이 패턴 불필요.

Error Boundary 가 자리 잡으면 production 사고가 사용자 경험에 미치는 영향이 한 단계 떨어진다. 19편부터는 디자인·스타일 — React 의 CSS 전략 3대 옵션 비교.

React 교재 19편 — CSS 전략 비교. Tailwind · CSS Modules · CSS-in-JS 중 무엇을 언제.