[Next.js]초기 단계 프로젝트에서 에러 핸들링은 어디까지 해야 할까?

오병훈·2025년 4월 15일

error boundary nextjs swyp9기 스위프 에러처리 팀 프로젝트

[팀 프로젝트] SWYP 9기

목록 보기

3/9

Next.js에서 에러 처리 전략 잡기: error.tsx vs react-error-boundary

최근 프로젝트에서 에러 처리 구조를 어떻게 잡을 것인가에 대해 고민이 많았다.
특히 Next.js (App Router) 환경에서는 error.tsx를 통한 전역 에러 처리 기능이 기본 제공되기 때문에, React의 react-error-boundary와 어떻게 조합할지 전략이 중요했다.

🤔 어떤 방식이 좋을까?

React 기반 프로젝트에서는 일반적으로 두 가지 방식이 존재한다.

구분	설명	사용 시점
`error.tsx`	Next.js App Router에서 제공하는 페이지 단위 에러 처리	페이지 전체가 터졌을 때
`react-error-boundary`	컴포넌트 단위로 에러를 잡아 fallback UI를 보여줌	특정 섹션만 에러날 때

🧱 현재 내가 선택한 방식

현재 프로젝트는 초기 단계이기 때문에 다음과 같은 전략을 선택했다.

✅ 전역 에러는 error.tsx로 먼저 처리하고, 후에 컴포넌트 단위에서 필요할 경우 react-error-boundary를 추가하자!

이유는?

개발 초기라 구조가 복잡하지 않음
전체 페이지가 깨지는 경우만 방어해도 충분
나중에 기능이 많아질수록 자연스럽게 세분화 가능

✨ error.tsx 설정 예시

'use client';

import { useEffect } from 'react';

type GlobalErrorProps = {
  error: Error;
  reset: () => void;
};

export default function GlobalError({ error, reset }: GlobalErrorProps) {
  useEffect(() => {
    console.error('🚨 Global error:', error);
  }, [error]);

  return (
    <div className="flex flex-col items-center justify-center min-h-screen p-6 text-center text-gray-800 bg-white">
      <h1 className="text-2xl font-bold mb-4">⚠️ 문제가 발생했어요</h1>
      <p className="mb-6">{error.message}</p>
      <button
        onClick={() => reset()}
        className="px-4 py-2 border border-gray-300 rounded-md bg-gray-100 hover:bg-gray-200 transition"
      >
        다시 시도하기
      </button>
    </div>
  );
}