화이트 스크린 오브 데스 방지: Next.js 에러 경계 마스터하기 🛡️

Source: Dev.to

React 트리의 취약성

React 애플리케이션에서 가장 위험한 동작 중 하나는 처리되지 않은 JavaScript 예외를 어떻게 다루는가 입니다. 기본적으로 단일 컴포넌트가 오류를 발생시키면(예: 정의되지 않은 API 응답에서 .map()을 호출하려 할 때) React는 전체 컴포넌트 트리를 즉시 언마운트합니다. 복잡한 대시보드를 보는 B2B SaaS 사용자에게는 날씨 위젯 하나가 실패해도 화면 전체가 완전히 빈 화면, 즉 White Screen of Death가 나타납니다.

Smart Tech Devs에서는 프론트엔드를 복원력 있게 설계합니다. 비핵심 컴포넌트에서 발생한 실패가 핵심 애플리케이션을 크래시시키면 안 됩니다. 우리는 Next.js App Router에서 Error Boundaries를 활용해 이 문제를 해결합니다.

error.tsx 로 격리 설계하기

Next.js 13+에서는 파일 시스템 기반 라우팅 규칙을 도입해 Error Boundaries를 매우 우아하게 구현할 수 있게 되었습니다. 특정 라우트 세그먼트에 error.tsx 파일을 생성하면 해당 세그먼트와 그 하위 컴포넌트가 자동으로 React Error Boundary 로 감싸집니다.

Step 1: 세밀한 Error Boundary 만들기

청구서 위젯이 실패하면 청구서 섹션만 오류 상태를 표시하도록 하고 싶습니다. 사이드바, 헤더 및 다른 위젯은 계속 동작해야 합니다.

// app/dashboard/invoices/error.tsx
"use client"; // Error components MUST be Client Components

import { useEffect } from "react";

export default function InvoicesError({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  useEffect(() => {
    // Log the error to an external service like Sentry
    console.error("Invoice Widget Failed:", error);
  }, [error]);

  return (
    <div className="p-4">
      <h2 className="text-xl font-bold">Failed to load invoices.</h2>
      <p>We encountered a network issue.</p>

      {/* The 'reset' function attempts to re‑render the failed segment */}
      <button
        onClick={() => reset()}
        className="bg-red-600 text-white px-4 py-2 rounded shadow"
      >
        Try Again
      </button>
    </div>
  );
}

Fallback 계층 구조

App Router의 장점은 중첩된 계층 구조에 있습니다. app/dashboard/invoices/page.tsx에서 오류가 발생하면 Next.js는 가장 가까운 error.tsx 파일을 찾습니다. invoices 폴더에 파일이 있으면 해당 페이지 컴포넌트만 오류 UI 로 교체됩니다.

전역적인, 치명적인 실패에 대비하려면 루트 app/ 디렉터리에 global-error.tsx 파일을 항상 포함시켜야 합니다. 이는 최후의 방어선 역할을 하여 루트 레이아웃이 크래시되더라도 사용자는 원시 브라우저 오류 대신 브랜드화된 전문적인 “Something went wrong” 페이지를 보게 됩니다.

결론

엔터프라이즈 소프트웨어에서는 실패가 불가피하지만, 치명적인 UI 크래시는 선택 사항입니다. 복잡하거나 위험한 데이터‑fetching 컴포넌트 주변에 Next.js Error Boundaries를 전략적으로 배치함으로써 오류를 격리하고, 사용자 경험을 보호하며, 압박이 가해져도 우아하게 감소하는 SaaS 플랫폼을 구축할 수 있습니다.