---
title: 'Suspense & ErrorBoundary 딥다이브: 던지는 컴포넌트의 세계'
marp: true
paginate: true
theme: yceffort
tags:
- react
- suspense
- error-boundary
date: 2026-07-29
description: 'throw 하나로 이해하는 선언적 로딩과 에러 처리 — 개념부터 reconciler 내부 동작, 실무 경계 설계, React Query 연계까지'
published: true
---
# Suspense & ErrorBoundary 딥다이브
던지는 컴포넌트의 세계 — throw 하나로 이해하는 선언적 로딩과 에러 처리
@yceffort
---
## 이 강의에서 다루는 것
1. 왜 이 둘을 **같이** 배우는가
2. **ErrorBoundary** — 개념, 동작, 잡지 못하는 것들
3. **Suspense** — fallback 뒤에서 벌어지는 일
4. **원리 딥다이브** — React 내부에서 throw는 어떻게 처리되는가
5. **실무** — 경계 배치, 깜빡임, waterfall, 리셋, 로깅
6. **React Query**와 조합하기
Part 1~5가 끝날 때마다 **정리와 퀴즈**가 있다.
---
## 이 강의의 메시지
> Suspense와 ErrorBoundary는 별개의 기능이 아니다.
> **컴포넌트가 렌더링을 포기하고 무언가를 throw했을 때**, 그것을 받아주는 하나의 메커니즘의 두 얼굴이다.
- promise를 throw하면 → 가장 가까운 **Suspense**가 받는다
- Error를 throw하면 → 가장 가까운 **ErrorBoundary**가 받는다
이 한 문장을 이해하면, 두 기능의 동작이 전부 같은 그림 위에 놓인다.
---
## Part 0 — 왜 이 둘을 같이 배우는가
---
## 명령형 방식: 우리가 매일 쓰던 코드
```jsx
function UserProfile({id}) {
const [user, setUser] = useState(null)
const [loading, setLoading] = useState(true)
const [error, setError] = useState(null)
useEffect(() => {
setLoading(true)
fetchUser(id)
.then(setUser)
.catch(setError)
.finally(() => setLoading(false))
}, [id])
if (loading) return
if (error) return
return
}
```
---
## 이 코드의 문제
- **모든 컴포넌트마다 반복**된다 — loading/error 분기가 성공 화면보다 길다
- 로딩 상태의 **조합**이 컴포넌트 수만큼 늘어난다 (스피너 3개가 각자 돈다)
- race condition, 언마운트 후 setState… 부수적인 버그의 온상
- "성공했을 때 어떤 화면인가"가 코드에서 잘 안 보인다
> 로딩과 에러는 **개별 컴포넌트의 관심사가 아니라, 화면 영역의 관심사**다.
---
## 선언적 경계라는 발상
```jsx
}>
}>
{/* 성공한 화면만 그린다 */}
```
- `Profile`은 **데이터가 이미 있다고 가정하고** 성공 화면만 그린다
- 로딩 중이라면? → 렌더를 **포기하고 promise를 throw** → Suspense가 받는다
- 실패했다면? → 렌더를 **포기하고 Error를 throw** → ErrorBoundary가 받는다
분기가 컴포넌트 밖으로, **트리 구조**로 올라갔다.
---
## 두 경계의 대칭
| 관점 | Suspense | ErrorBoundary |
| ----------- | ------------------------- | ------------------------------ |
| 받는 것 | promise | Error |
| 의미 | "아직 준비 안 됨" | "실패함" |
| 보여주는 것 | `fallback` prop | fallback UI (직접 구현) |
| 복귀 방법 | promise resolve → 자동 | 리셋 (수동) |
| 탐색 방향 | 가장 가까운 조상 Suspense | 가장 가까운 조상 ErrorBoundary |
**같은 구조, 다른 페이로드.** Part 3에서 React 소스로 이 대칭을 직접 확인한다.
---
## Part 1 — ErrorBoundary: 개념과 동작
---
## 렌더 중 에러가 나면 무슨 일이 벌어지는가
```jsx
function Product({item}) {
// item이 undefined면? → TypeError
return
{item.name}
}
```
ErrorBoundary가 하나도 없다면:
- React는 **트리 전체를 언마운트**한다 (React 16부터)
- 사용자는 **빈 흰 화면**을 본다
- "일부가 깨진 UI를 남겨두는 것이 더 위험하다"는 판단 — 결제 화면에서 금액이 잘못 보이는 것보다 아무것도 안 보이는 게 낫다
> 경계가 없으면, 버튼 하나의 에러가 **앱 전체를 지운다**.
---
## ErrorBoundary 최소 구현
```jsx
class ErrorBoundary extends React.Component {
state = {error: null}
static getDerivedStateFromError(error) {
return {error} // 이 state로 fallback을 그린다
}
componentDidCatch(error, info) {
logError(error, info.componentStack) // 로깅은 여기서
}
render() {
if (this.state.error) return this.props.fallback
return this.props.children
}
}
```
자식 트리에서 렌더 중 에러가 throw되면, 이 컴포넌트가 받아서 **자기 영역만** fallback으로 바꾼다.
---
## 두 라이프사이클의 역할 분리
| 구분 | `getDerivedStateFromError` | `componentDidCatch` |
| --------- | ------------------------------ | ------------------------------ |
| 실행 시점 | **render phase** | **commit phase** |
| 하는 일 | fallback을 그릴 state 반환 | 로깅 등 사이드이펙트 |
| 순수해야? | ✅ (static, 사이드이펙트 금지) | ❌ (자유롭게) |
| 받는 것 | `error` | `error`, `info.componentStack` |
**render phase**는 무엇을 그릴지 계산하는 단계, **commit phase**는 그 결과를 실제 DOM에 반영하는 단계다. render phase는 동시성 모드에서 중단·재실행될 수 있어서, "무엇을 그릴까"(순수)와 "무엇을 기록할까"(사이드이펙트)를 분리해 놓은 것.
---
## 왜 아직도 클래스 컴포넌트인가
표면적으로는 "`getDerivedStateFromError`에 대응하는 훅이 없어서". (2018년 훅 발표 때 "곧 추가될 예정"이라던 그 훅이 8년째 없다)
진짜 이유는 **실행 모델의 불일치**:
- 훅은 **내 함수가 실행되는 동안** 동작하는 API
- 에러 캐치는 정반대 — **내 렌더가 끝난 뒤**, 자식이 던졌을 때 React가 나를 다시 불러줘야 한다
- 클래스에는 렌더 사이에도 살아있는 **인스턴스**와, React가 임의 시점에 호출할 **메서드**가 있다. 함수형은 렌더 = 함수 호출 그 자체라 그 자리가 없다
(Part 3에서 React가 클래스 컴포넌트를 찾아 올라가는 코드로 이를 확인한다)
실무 결론: **클래스를 직접 쓰지 말고 `react-error-boundary`를 쓴다.** 앱에서 클래스가 정당한 거의 유일한 자리가 여기다.
---
## 잡지 못하는 것 1 — 이벤트 핸들러
```jsx
function BuyButton() {
const handleClick = () => {
throw new Error('결제 실패') // ErrorBoundary에 안 잡힌다!
}
return
}
```
- ErrorBoundary는 **렌더링 중** 던져진 에러만 잡는다
- 이벤트 핸들러는 렌더링이 끝난 뒤, 브라우저 이벤트에 반응해 실행된다 — React의 렌더 try/catch 바깥이다
- 화면이 깨질 일이 없으니 fallback으로 바꿀 이유도 없다는 설계
- 안 잡힌 에러는 **전역(window)으로 흘러가** 콘솔에 찍힐 뿐, 이미 커밋된 화면은 그대로다 — 렌더 에러처럼 흰 화면이 되지는 않는다
핸들러 안에서는 **직접 try/catch** 해야 한다. (경계로 보내는 방법은 Part 4에서)
---
## 잡지 못하는 것 2 — 비동기 콜백
```jsx
useEffect(() => {
setTimeout(() => {
throw new Error('타이머 안') // ❌ 안 잡힌다
}, 1000)
fetchUser(id).then(() => {
throw new Error('then 안') // ❌ 안 잡힌다
})
}, [id])
```
`setTimeout`, promise 콜백이 실행될 시점에 렌더링은 이미 끝나 있다. **호출 스택이 다르다.**
단, 헷갈리지 말 것:
```jsx
useEffect(() => {
throw new Error('effect 본문') // ✅ 이건 잡힌다
}, [])
```
effect 본문의 동기적 throw는 React가 커밋 과정에서 처리하므로 **경계에 잡힌다**.
---
## 잡지 못하는 것 3, 4
**자기 자신의 에러**
```jsx
class ErrorBoundary extends React.Component {
render() {
if (this.state.error) return // 💥
...
}
}
```
fallback 자체가 던지면 **그 위의** 경계로 올라간다. 경계는 자식만 보호한다.
**SSR 에러** — 서버 렌더 중 에러는 클래스 ErrorBoundary의 라이프사이클로 처리되지 않는다. 스트리밍 SSR에서는 다른 메커니즘(가장 가까운 Suspense까지 지우고 클라이언트에서 재시도)이 동작한다. (Part 3 후반)
---
## 실무에서는: react-error-boundary
```jsx
import {ErrorBoundary} from 'react-error-boundary'
function Fallback({error, resetErrorBoundary}) {
return (
문제가 생겼습니다: {error.message}
)
}
;
```
클래스 보일러플레이트 없이 fallback, 로깅, **리셋**(Part 4)까지 제공한다. 사실상 표준.
---
## Part 1 정리
- 경계 없는 렌더 에러 = **트리 전체 언마운트** (흰 화면)
- `getDerivedStateFromError` → 무엇을 그릴까 (render phase, 순수)
- `componentDidCatch` → 무엇을 기록할까 (commit phase, 사이드이펙트)
- 잡는 것: **렌더링, 라이프사이클, 생성자, effect 본문**의 에러
- 못 잡는 것: **이벤트 핸들러, 비동기 콜백, 자기 자신, SSR**
- 직접 만들지 말고 `react-error-boundary`
---
## 퀴즈 1 — ErrorBoundary에 잡힐까?
각 코드의 에러가 부모 ErrorBoundary에 잡히면 O, 아니면 X.
```jsx
function A() {
return
{data.name}
// (1) 렌더 — data는 undefined
}
const handleClick = () => {
throw new Error() // (2) 버튼의 클릭 핸들러
}
useEffect(() => {
throw new Error() // (3) effect 본문
}, [])
useEffect(() => {
fetch('/api').then(() => {
throw new Error() // (4) promise 콜백
})
}, [])
```
---
## 퀴즈 1 — 정답
| 코드 | 정답 | 이유 |
| ---- | ----- | --------------------------------------------------- |
| (1) | **O** | 렌더 중 throw — 경계의 본래 목적 |
| (2) | **X** | 이벤트 핸들러 — 렌더 바깥의 호출 스택 |
| (3) | **O** | effect **본문**의 동기 throw는 커밋 과정에서 잡힌다 |
| (4) | **X** | promise 콜백 — 렌더도 커밋도 아닌 나중 시점 |
> 판별 기준은 "어디에 썼나"가 아니라 **"React가 실행해주는 흐름 안에서 던져졌나"**.
---
## Part 2 — Suspense: 개념과 동작
---
## Suspense 기본형
```jsx
}>
```
- `Profile`(또는 그 아래 누군가)이 "아직 준비 안 됨"을 선언하면 `fallback`을 대신 보여준다
- 준비가 끝나면 **자동으로** 실제 콘텐츠로 교체된다
- 로딩 상태를 **어디에 보여줄지**를 트리 구조로 선언하는 컴포넌트
그런데 — "아직 준비 안 됨"을 **누가, 어떻게** 선언하는가?
---
## 무엇이 suspend를 일으키는가
| 소스 | suspend? |
| ------------------------------------------------------------------------- | -------- |
| `React.lazy()` 코드 스플리팅 | ✅ |
| `use(promise)` (React 19) | ✅ |
| Suspense 지원 프레임워크·라이브러리 (Next.js RSC, TanStack Query, Relay…) | ✅ |
| 컴포넌트 안에서 직접 `fetch` | ❌ |
| `useEffect` 안의 데이터 페칭 | ❌ |
**fetch를 쓴다고 저절로 suspend되지 않는다.** suspend는 특정한 프로토콜을 따르는 코드만 일으킨다. (표는 **클라이언트 컴포넌트 기준** — async 서버 컴포넌트의 `await`은 서버 렌더러가 같은 신호로 바꿔준다.) 그 프로토콜이 —
---
## suspend의 정체: promise를 throw한다
```jsx
function Profile() {
const user = resource.read()
// read()의 내부:
// 데이터 있음 → 값 반환
// 로딩 중 → throw promise ← 이것이 suspend
// 실패 → throw error ← ErrorBoundary로
return
{user.name}
}
```
- JavaScript의 `throw`는 Error 전용이 아니다 — **아무 값이나 던질 수 있다**
- React는 렌더 중 잡힌 값이 **thenable**(then 메서드를 가진 객체)이면 "에러"가 아니라 "**기다려 달라는 신호**"로 해석한다
이 한 가지 트릭이 Suspense의 전부다.
---
## 가짜 Suspense 리소스 — 직접 만들어보기
```jsx
function createResource(promise) {
let state = {status: 'pending', result: null}
promise.then(
(value) => (state = {status: 'success', result: value}),
(error) => (state = {status: 'error', result: error}),
)
return {
read() {
if (state.status === 'pending') throw promise // Suspense가 받는다
if (state.status === 'error') throw state.result // ErrorBoundary가 받는다
return state.result
},
}
}
```
이 몇 줄로 두 경계에 모두 연결됐다. 라이브러리들이 하는 일도 본질적으로 이것(+ 캐싱)이다.
---
## promise가 resolve되면?
```
1. Profile 렌더 → throw promise
2. React: 가장 가까운 Suspense를 찾아 fallback을 화면에 표시
3. React: 잡아둔 promise에 "끝나면 알려줘"라고 .then을 걸어둠
4. 데이터 도착 (promise resolve)
5. React: Profile을 처음부터 다시 렌더링
6. 이번엔 read()가 값을 반환 → fallback 대신 진짜 콘텐츠 표시
```
핵심: **멈춘 곳에서 이어지는 게 아니라, 처음부터 다시 실행된다.**
자바스크립트 함수는 중간에 일시정지했다가 재개할 수 없다. 그래서 React가 할 수 있는 일은 컴포넌트 함수를 한 번 더 호출하는 것뿐이다. 이때 리소스가 결과를 기억해두지 않았다면 read()는 또 promise를 던지고, 화면은 fallback에서 벗어나지 못한다. 결과를 캐시하는 리소스/라이브러리가 필요한 이유가 이것이다.
---
## fallback이 보이는 동안, 아래 트리는?
두 가지 상황을 구분해야 한다.
**① 최초 마운트 중 suspend** — 아직 아무것도 커밋된 적 없음. DOM도 state도 없는 상태에서 fallback만 커밋된다.
**② 이미 보이던 트리가 다시 suspend** (동기 업데이트)
```html
기존 콘텐츠
fallback
```
- 기존 콘텐츠를 **언마운트하지 않는다** — `display: none`으로 숨긴다
- 컴포넌트 **state는 그대로 유지**된다
- 준비되면 다시 보여주기만 하면 된다
이 "숨기기" 메커니즘이 내부의 Offscreen(현 Activity) 처리다.
---
## use() — React 19의 공식 입구
```jsx
import {use, Suspense} from 'react'
function Profile({userPromise}) {
const user = use(userPromise) // pending이면 suspend
return