Feat(#290): 렌더링 에러 바운더리(ErrorBoundary) 도입

[stringnine]

📌 관련 이슈

• Closes [Feat] 렌더링 에러 바운더리(ErrorBoundary) 도입 #290

🏷️ PR 타입

• ✨ 기능 추가 (Feature)
• 🐛 버그 수정 (Bug Fix)
• ♻️ 리팩토링 (Refactoring)
• 🗑️ 코드 제거 (Chore)
• 📝 문서 수정 (Documentation)
• 🎨 스타일 변경 (Style)
• ✅ 테스트 추가 (Test)

📝 작업 내용

렌더 단계 예외로 앱 전체가 흰 화면(white screen)으로 죽는 문제를 막기 위해 2겹 ErrorBoundary 안전망을 도입했습니다.

• 범용 ErrorBoundary 클래스 컴포넌트 추가 (getDerivedStateFromError + componentDidCatch, 폴백·로깅·reset 지원)
• 라우트 errorElement용 RouteErrorBoundary 추가 — 라우터 트리 내부 렌더/로더 에러를 잡아 기존 ServerErrorPage(500) 재활용 (SPA 네비게이션 유지)
• 최상단 폴백 RootErrorFallback 추가 — provider/ToastHost 등 라우터 바깥 catastrophic 에러 대비 (window.location 기반)
• main.tsx 최상단을 <ErrorBoundary>로 래핑, routes.tsx 루트 라우트에 errorElement 연결
• 에러 발생 시 console.error 로깅 — 추후 Sentry 등 외부 로깅 연동 지점(// TODO) 표시

동작 방식

• 페이지 렌더 중 에러 → 라우트 errorElement가 잡아 500 페이지 폴백 (홈으로 버튼 동작)
• 라우터 바깥 에러 → 최상단 클래스 경계가 잡아 새로고침 폴백 표시

✅ 체크리스트

공통

• 셀프 리뷰를 완료했습니다
• 코드 리뷰를 받을 준비가 완료되었습니다
• pnpm tsc --noEmit 타입 체크를 통과했습니다
• 브랜치명 컨벤션을 준수했습니다 (type/이슈번호-작업명)

📎 기타 참고사항

• 이벤트 핸들러/비동기 코드의 예외는 React 특성상 ErrorBoundary가 잡지 못합니다. 해당 케이스(SSE 응답 실패, mutation 실패 등)는 후속 이슈에서 다룹니다 → [Feat] AI 응답 실패(SSE run.failed) 사용자 피드백 처리 #291, [Feat] react-query 전역 에러 처리 (mutation 실패 토스트 안전망) #292, [Feat] API 네트워크 견고성 강화 (axios timeout/오프라인 + 에러 리다이렉트 정책 정리) #293
• 동작 확인: 임시 throw로 라우트 경계가 500 페이지로 폴백되는 것 및 콘솔 로깅을 로컬에서 검증했습니다.
• 외부 에러 로깅(Sentry 등) 연동 여부는 팀 결정 사항이라 연동 지점만 표시해두었습니다.

Summary by CodeRabbit

릴리스 노트

• 새 기능
  • 애플리케이션 에러 발생 시 사용자 친화적인 에러 화면 표시 기능 추가
  • 예기치 않은 오류 발생 상황에서 한 번의 클릭으로 페이지를 새로고침할 수 있는 기능 제공
  • 앱 전체 범위의 에러 처리 및 라우트별 에러 처리 강화로 안정성 개선

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: cf2c647f-1c21-45f2-8cc3-eeb2b0634506

📥 Commits

Reviewing files that changed from the base of the PR and between 45ff576 and 23b4bce.

📒 Files selected for processing (5)

• src/app/router/routes.tsx
• src/main.tsx
• src/shared/components/ErrorBoundary.tsx
• src/shared/components/RootErrorFallback.tsx
• src/shared/router/RouteErrorBoundary.tsx

---

📝 Walkthrough

Walkthrough

렌더 단계에서 발생하는 예외를 안전하게 처리하기 위해 ErrorBoundary를 도입합니다. 라우트 레벨과 최상단 레벨에서 각각 다른 폴백 UI를 표시하며, 라우터 컨텍스트 유무에 따라 적절한 복구 메커니즘을 제공합니다.

Changes

에러 바운더리 구현 및 통합

Layer / File(s)	Summary
ErrorBoundary 클래스 구현 src/shared/components/ErrorBoundary.tsx	getDerivedStateFromError와 componentDidCatch를 구현하여 렌더 단계 예외를 상태에 저장하고, 함수형 또는 노드 기반 폴백 UI를 조건부 렌더링. reset() 메서드로 에러 상태 초기화 가능.
폴백 UI 컴포넌트 src/shared/components/RootErrorFallback.tsx, src/shared/router/RouteErrorBoundary.tsx	RootErrorFallback은 최상단 에러 시 window.location.reload()로 전체 페이지 새로고침. RouteErrorBoundary는 useRouteError()로 라우트 에러 수집 후 ServerErrorPage 렌더링.
애플리케이션 통합 src/main.tsx, src/app/router/routes.tsx	main.tsx에서 전체 렌더 트리를 ErrorBoundary로 감싸고 RootErrorFallback을 fallback으로 설정. routes.tsx의 루트 라우트에 RouteErrorBoundary를 errorElement로 지정.

Sequence Diagram

sequenceDiagram
  participant User as 사용자
  participant App as 애플리케이션
  participant RootEB as RootErrorBoundary
  participant Router as 라우터
  participant RouteEB as RouteErrorBoundary
  participant Component as 페이지 컴포넌트
  
  User->>App: 페이지 로드/네비게이션
  App->>RootEB: 렌더 시작
  RootEB->>Router: 정상 진행
  Router->>RouteEB: errorElement 설정
  RouteEB->>Component: 라우트 렌더링
  
  alt 라우터 내부 에러
    Component-->>RouteEB: 예외 발생
    RouteEB->>RouteEB: useRouteError() 수집
    RouteEB-->>User: ServerErrorPage 표시
  else 라우터 외부 에러
    App-->>RootEB: 예외 발생
    RootEB->>RootEB: 폴백 상태 전환
    RootEB-->>User: RootErrorFallback 표시
    User->>User: 새로고침 버튼 클릭
    User->>User: window.location.reload()
  end

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• Team-Proovy/Proovy-front#284: 메인 PR의 라우트/루트 ErrorBoundary가 폴백으로 ServerErrorPage(및 ProovyIcon)를 렌더링하도록 추가한 것과, 리트리브된 PR이 ServerErrorPage 및 공통 ErrorPageLayout/ProovyIcon의 에러 페이지 UI를 재구성한 변경이 직접 맞물립니다.

Suggested labels

feature

Suggested reviewers

• L0521
• dev-ldy03

Poem

🐰 렌더링의 악마도 잡아낸다
하얀 화면 대신 보기 좋은 폴백
ErrorBoundary 두 계층, 안전한 성
사용자는 새로고침 버튼으로 행복해져
예외는 콘솔에 기록되고... 조용히 ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	PR 제목이 주요 변경사항인 ErrorBoundary 도입을 명확하고 간결하게 요약하고 있습니다.
Description check	✅ Passed	PR 설명이 템플릿의 모든 주요 섹션을 포함하고 있으며, 기능 구현 내용, 동작 방식, 체크리스트를 완벽하게 기재했습니다.
Linked Issues check	✅ Passed	PR의 모든 코드 변경사항이 #290의 목표인 ErrorBoundary 도입을 완벽하게 충족하고 있습니다.
Out of Scope Changes check	✅ Passed	모든 변경사항이 #290의 ErrorBoundary 도입 목표에 직접 관련되어 있으며, 범위 밖의 변경사항이 없습니다.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/290-error-boundary

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}