본문으로 건너뛰기

React Deep · EP 04

React 에러 바운더리 제대로 쓰기

React 에러 바운더리가 클래스형인 이유, resetKeys로 재시도하는 패턴, 라우터 단위 격리 전략을 정리합니다.

· 3분 읽기

React 에러 바운더리 제대로 쓰기

개요

React에서 렌더 중 에러가 throw되면 컴포넌트 트리 전체가 언마운트됩니다. 사용자에게 보이는 것은 흰 화면 하나뿐이죠. 에러 바운더리(error boundary)는 이 에러를 잡아서 하위 트리만 폴백 UI로 대체하는 장치입니다. 단순히 “감싸기” 이상으로 제대로 쓰기 위해 알아야 할 것들을 정리했습니다.

클래스형이 여전한 이유

에러 바운더리는 클래스 컴포넌트의 static getDerivedStateFromError와 componentDidCatch 생명주기를 통해서만 동작합니다. React 공식 문서도 “아직 함수 컴포넌트로 에러 바운더리를 작성하는 방법은 없다”고 명시하고 있어서, 함수형 시대에도 이 부분만은 클래스를 쓰거나 react-error-boundary 같은 라이브러리를 씁니다.

import { Component, type ErrorInfo, type ReactNode } from 'react';

interface Props {
  fallback: ReactNode;
  children: ReactNode;
}

interface State {
  hasError: boolean;
}

class ErrorBoundary extends Component<Props, State> {
  state: State = { hasError: false };

  static getDerivedStateFromError(): State {
    return { hasError: true };
  }

  componentDidCatch(error: Error, info: ErrorInfo) {
    console.error('ErrorBoundary caught:', error, info.componentStack);
  }

  render() {
    if (this.state.hasError) {
      return this.props.fallback;
    }
    return this.props.children;
  }
}

역할 분담이 중요합니다. getDerivedStateFromError는 폴백을 렌더하기 위한 state 갱신, componentDidCatch는 로깅 같은 부수효과 담당입니다.

reset 패턴

에러가 한 번 발생하면 바운더리는 계속 폴백 상태에 머뭅니다. “다시 시도” 버튼을 만들려면 state를 초기화할 방법이 필요한데, 대표적으로 두 가지가 있습니다.

방법 1 — key로 리마운트: 에러가 난 트리를 key 변경으로 통째로 다시 마운트합니다.

function Editor() {
  const [retryKey, setRetryKey] = useState(0);
  return (
    <ErrorBoundary key={retryKey} fallback={<Fallback onRetry={() => setRetryKey((k) => k + 1)} />}>
      <HeavyWidget />
    </ErrorBoundary>
  );
}

방법 2 — resetKeys (react-error-boundary): 특정 값이 바뀌면 자동으로 리셋됩니다. 라우트 파라미터가 바뀔 때 함께 초기화하는 데 유용합니다.

import { ErrorBoundary } from 'react-error-boundary';

function PostPage({ postId }: { postId: string }) {
  return (
    <ErrorBoundary
      fallbackRender={({ resetErrorBoundary }) => (
        <div>
          <p>글을 불러오지 못했습니다.</p>
          <button onClick={resetErrorBoundary}>다시 시도</button>
        </div>
      )}
      resetKeys={[postId]}
    >
      <Post postId={postId} />
    </ErrorBoundary>
  );
}

한 가지 주의할 점: 이벤트 핸들러 안의 에러, setTimeout 콜백의 에러, 서버 컴포넌트의 에러는 바운더리가 잡지 못습니다. 그런 에러는 try/catch로 직접 처리해야 합니다.

라우터 단위 격리

가장 효과가 컸던 전략은 “페이지 단위 + 위젯 단위” 이중 격리였습니다. 라우트마다 바운더리를 붙이면 한 페이지가 죽어도 사이드바·헤더 같은 공통 UI는 살아있고, 다른 페이지로 이동도 가능합니다.

<Route
  path="/dashboard"
  element={
    <ErrorBoundary fallback={<PageErrorFallback />}>
      <Dashboard />
    </ErrorBoundary>
  }
/>

대시보드의 개별 위젯에도 바운더리를 붙이면 차트 하나가 죽어도 나머지 위젯은 정상 동작합니다. 격리 단위가 작을수록 폭발 반경이 줄어드는 셈입니다.

로깅과 연동하기

componentDidCatch나 onError 콜백에서 Sentry 같은 모니터링 도구로 에러를 전송합니다. 이때 componentStack을 함께 보내면 어느 컴포넌트에서 터졌는지 추적이 훨씬 쉬워집니다. 사용자가 “다시 시도”를 눌렀는지 여부를 이벤트로 남겨두면 폴백 UX의 실패율도 측정할 수 있습니다.

마무리

에러 바운더리는 “있는지 없는지”보다 “어디까지 격리했는지”가 중요했습니다. 페이지 단위로 크게, 위젯 단위로 작게 격리하고, reset 패턴으로 복구 경로까지 제공하면 흰 화면 사고를 상당히 줄일 수 있습니다. 이 글의 예시처럼 react-error-boundary를 쓰면 클래스를 직접 관리할 부담도 덜 수 있습니다.

Related

· 18 min read Build Logs

damon-chat-desk 구축기 — 로컬 에이전트 데몬의 /ws 위에 얇은 웹 데스크를 얹기

로컬 AI 에이전트 데몬(damon-agent-core) 위에 정적 SPA 채팅 데스크를 얹었습니다. OpenAI 호환 경로 대신 /ws JSON-RPC v2와 일회용 ws_ticket을 고른 이유, 툴 실행 아코디언·turn.steer·plan.respond CAS·session.fork, 메모리 게이트(-32011)를 UI 문장으로 옮기는 법, ⌘K 팔레트, https 페이지에서 loopback 데몬에 붙을 수 없을 때의 demo 폴백까지 — PR 4건 +18,477줄, 테스트 223개, 번들 375kB의 기록입니다.

프론트엔드AI
→
· 15 min read Build Logs

AI 과제 지도(assignment-map) 구축기 — 수집기 흰 화면 복구부터 18종 레퍼런스 기반 UI 개편까지

채용 과제·해커톤의 AI 정책과 마감을 매일 수집하는 과제 지도를 6일 동안 PR 16건으로 고도화했습니다. evidence 문자열 하나가 배포 화면을 통째로 죽인 장애와 그 뿌리 수정, 18종 레퍼런스 실측에서 나온 PR A~E, npm ci 앞에서 돌던 테스트가 배포를 막은 CI 함정까지 실제 수치로 정리합니다.

프론트엔드AI
→