error.tsx 파일 규칙을 사용하면, 중첩된 경로에서 발생하는 예기치 않은 런타임 오류를 효율적으로 처리할 수 있다. React의 Error Boundary가 경로 세그먼트와 중첩된 하위 error.tsx를 자동으로 래핑해주기 때문에, 특정 경로에서 발생하는 오류에 맞는 UI를 손쉽게 구성할 수 있다.
오류가 발생한 세그먼트를 격리하면서도 나머지 애플리케이션은 정상적으로 유지시킬 수 있다. 또한, 전체 페이지를 다시 로드하지 않고도 오류 복구를 시도할 수 있는 기능을 제공할 수 있다. 이를 구현하려면 경로 세그먼트 내부에 error.tsx 파일을 추가하고, 오류를 처리할 React 컴포넌트를 export하여 원하는 오류 UI를 정의하면 된다.
'use client' // Error components must be Client Components
import { useEffect } from 'react'
export default function Error({
error,
reset,
}: {
error: Error
reset: () => void
}) {
useEffect(() => {
// Log the error to an error reporting service
console.error(error)
}, [error])
return (
<div>
<h2>Something went wrong!</h2>
<button
onClick={
// Attempt to recover by trying to re-render the segment
() => reset()
}
>
Try again
</button>
</div>
)
}
error.tsx는 어떻게 동작하는가?
error.tsx 파일은 중첩된 자식 세그먼트나 page.tsx 컴포넌트를 자동으로 감싸는 React Error Boundary를 생성한다. 이 파일에서 내보낸 React 컴포넌트는 폴백 컴포넌트로 사용되며, Error Boundary 내부에서 오류가 발생하면 해당 오류가 감지되고 폴백 컴포넌트가 렌더링된다.
폴백 오류 컴포넌트가 활성화되더라도 Error Boundary 위에 있는 레이아웃은 영향을 받지 않으며, 기존의 상태를 유지한다. 또한, 오류 컴포넌트는 사용자가 오류를 복구할 수 있는 기능을 제공할 수 있다.
오류 복구
오류의 원인은 일시적인 것일 수 있다. 이러한 경우, 다시 시도하기만 하면 문제가 해결될 수 있다. 오류 컴포넌트는 reset() 함수를 사용하여 사용자에게 오류에서 복구를 시도하라는 메시지를 표시할 수 있다. 이 함수가 실행되면 Error Boundary의 내용을 다시 렌더링하려고 시도하며, 성공하면 폴백 오류 컴포넌트가 다시 렌더링된 결과로 대체된다.
중첩된 경로에서 오류가 발생하면, 가장 가까운 error.tsx 파일이 그 오류를 처리한다. 예를 들어, 하위 경로에 error.tsx 파일이 있다면 해당 파일이 오류를 처리하며, 상위 경로의 error.tsx 는 아무 동작도 하지 않는다.
반대로, 하위 경로에 error.tsx 파일이 없다면, 오류는 상위 경로로 전파되어 상위 경로의 error.tsx가 이를 처리하게 된다. 따라서 중첩된 경로마다 error.tsx 를 배치하면 각 경로에서 발생하는 오류를 독립적으로 처리할 수 있다.
레이아웃에서 오류 처리하기
레이아웃에서 발생한 오류는 같은 경로의 error.tsx 로 처리되지 않는다. 이는 레이아웃과 같은 형제 경로의 중요한 UI가 오류와 상관없이 계속 표시되도록 설계된 것이다. 레이아웃에서 발생한 오류를 처리하려면, 해당 레이아웃을 감싸는 상위 경로에 error.tsx 파일을 추가해야 한다.
사용 방법
error.tsx가 있고, page.tsx에서 오류가 발생하면 page.tsx는 error.tsx로 대체된다. page.tsx에서 API를 호출하는 여러 개의 서버 컴포넌트를 Error Boundary로 감싸면 각각 fallback을 보여준다.
error.tsx가 있고, page.tsx 안에 API를 호출하는 오류가 발생한 여러 개의 서버 컴포넌트가 있지만 Error Boundary를 사용하지 않으면 page.tsx 전체가 가 error.tsx로 대체된다. Error Boundary를 사용했지만 fallback을 설정하지 않았을 경우, Error Boundary 내부는 빈상태로 남아있는다.
루트 레이아웃에서 오류 처리하기
루트 레이아웃에서 오류를 처리하려면 global-error.tsx를 사용해야 한다. global-error.tsx 는 전체 애플리케이션을 감싸는 폴백 UI로, 루트 레이아웃에서 발생하는 오류를 처리하고 전체 UI를 대체한다. 따라서, 이 파일에는 <html>과 <body> 태그를 명시적으로 작성해야 한다.
