React 에러 바운더리 제대로 쓰기
React 에러 바운더리가 클래스형인 이유, resetKeys로 재시도하는 패턴, 라우터 단위 격리 전략을 정리합니다.
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를 쓰면 클래스를 직접 관리할 부담도 덜 수 있습니다.