ํ”ผ๋“œ๋กœ ๋Œ์•„๊ฐ€๊ธฐ
Stop the White Screen of Death: Master Next.js Error Boundaries ๐Ÿ›ก๏ธ
Dev.toDev.to
Frontend

Next.js Error Boundaries๋ฅผ ํ†ตํ•œ UI ๊ฒฉ๋ฆฌ๋กœ White Screen of Death ์™„์ „ ์ฐจ๋‹จ

Stop the White Screen of Death: Master Next.js Error Boundaries ๐Ÿ›ก๏ธ

Prajapati Paresh2026๋…„ 5์›” 11์ผ2๋ถ„intermediate

Context

React์˜ ๊ธฐ๋ณธ ์˜ˆ์™ธ ์ฒ˜๋ฆฌ ๋ฐฉ์‹์— ๋”ฐ๋ฅธ ๋‹จ์ผ ์ปดํฌ๋„ŒํŠธ ์˜ค๋ฅ˜ ์‹œ ์ „์ฒด Component Tree๊ฐ€ ์–ธ๋งˆ์šดํŠธ๋˜๋Š” ๊ตฌ์กฐ์  ์ทจ์•ฝ์  ์กด์žฌ. ํŠนํžˆ B2B SaaS ๋Œ€์‹œ๋ณด๋“œ์™€ ๊ฐ™์ด ๋ณต์žกํ•œ ์ธํ„ฐํŽ˜์ด์Šค์—์„œ ๋น„ํ•ต์‹ฌ ์œ„์ ฏ์˜ ์žฅ์• ๊ฐ€ ์ „์ฒด ์„œ๋น„์Šค ์ค‘๋‹จ์œผ๋กœ ์ด์–ด์ง€๋Š” ๊ฐ€์šฉ์„ฑ ๋ฌธ์ œ ๋ฐœ์ƒ.

Technical Solution

  • Next.js App Router์˜ ํŒŒ์ผ ์‹œ์Šคํ…œ ๊ธฐ๋ฐ˜ ๋ผ์šฐํŒ…์„ ํ™œ์šฉํ•œ error.tsx ๋ฐฐ์น˜๋กœ Segment ๋‹จ์œ„ Error Boundary ๊ตฌ์ถ•
  • ์˜ค๋ฅ˜ ๋ฐœ์ƒ ์ง€์ ์—์„œ ๊ฐ€์žฅ ๊ฐ€๊นŒ์šด error.tsx๋ฅผ ํƒ์ƒ‰ํ•˜๋Š” ๊ณ„์ธต์  Fallback ๊ตฌ์กฐ ์„ค๊ณ„๋ฅผ ํ†ตํ•œ ์˜ํ–ฅ ๋ฒ”์œ„ ์ตœ์†Œํ™”
  • use client ์ง€์‹œ์–ด๋ฅผ ํ†ตํ•œ Client Component ๊ตฌํ˜„์œผ๋กœ ๋Ÿฐํƒ€์ž„ ์˜ˆ์™ธ ์บก์ฒ˜ ๋ฐ ์‚ฌ์šฉ์ž ์ธํ„ฐํŽ˜์ด์Šค ์ œ์–ด
  • reset() ํ•จ์ˆ˜๋ฅผ ํ†ตํ•œ ์‹คํŒจํ•œ ์„ธ๊ทธ๋จผํŠธ์˜ ์žฌ๋ Œ๋”๋ง ์‹œ๋„๋กœ ์„œ๋น„์Šค ๋ณต๊ตฌ ๋ฉ”์ปค๋‹ˆ์ฆ˜ ์ œ๊ณต
  • ๋ฃจํŠธ ๋””๋ ‰ํ† ๋ฆฌ ๋‚ด global-error.tsx ๋ฐฐ์น˜๋ฅผ ํ†ตํ•œ ์ตœ์ƒ์œ„ Layout ๋ถ•๊ดด ๋Œ€๋น„ ์ตœ์ข… ๋ฐฉ์–ด์„  ๊ตฌ์ถ•
  • Sentry ๋“ฑ ์™ธ๋ถ€ ๋กœ๊น… ์„œ๋น„์Šค ์—ฐ๋™์„ ์œ„ํ•œ useEffect ๊ธฐ๋ฐ˜์˜ ์—๋Ÿฌ ํŠธ๋ž˜ํ‚น ๋กœ์ง ํ†ตํ•ฉ

1. ๋ฐ์ดํ„ฐ ํŽ˜์นญ ์œ„ํ—˜๋„๊ฐ€ ๋†’์€ ๋…๋ฆฝ์  ์œ„์ ฏ ๋‹จ์œ„๋กœ `error.tsx`๋ฅผ ๋ฐฐ์น˜ํ–ˆ๋Š”๊ฐ€

2. ์ตœ์ƒ์œ„ ๋ฃจํŠธ์— `global-error.tsx`๋ฅผ ๊ตฌํ˜„ํ•˜์—ฌ ์ตœ์•…์˜ ์ƒํ™ฉ์—์„œ๋„ ๋ธŒ๋žœ๋“œ UI๋ฅผ ์œ ์ง€ํ•˜๋Š”๊ฐ€

3. ์—๋Ÿฌ UI ๋‚ด์— `reset` ํ•จ์ˆ˜๋ฅผ ํฌํ•จํ•˜์—ฌ ์‚ฌ์šฉ์ž๊ฐ€ ์ˆ˜๋™์œผ๋กœ ๋ณต๊ตฌ๋ฅผ ์‹œ๋„ํ•  ์ˆ˜ ์žˆ๋Š” ๊ฒฝ๋กœ๋ฅผ ์ œ๊ณตํ–ˆ๋Š”๊ฐ€

4. ์—๋Ÿฌ ์บก์ฒ˜ ์‹œ ์™ธ๋ถ€ ๋ชจ๋‹ˆํ„ฐ๋ง ๋„๊ตฌ๋กœ ์ •๋ฐ€ํ•œ ๋กœ๊ทธ๋ฅผ ์ „์†กํ•˜๋Š” ๋กœ์ง์ด ํฌํ•จ๋˜์—ˆ๋Š”๊ฐ€

์›๋ฌธ ์ฝ๊ธฐ