Next.js 13 / 08. Error Hadling

Intro

error.js 파일 규칙을 사용하면 중첩된 경로에서 런타임 오류(runtime errors)를 우아하게 처리할 수 있s다.

경로 세그먼트와 중첩된 자식들을 React Error Boundary로 자동으로 감싼다.
file-system hierarchy를 사용하여 특정 세그먼트에 맞춤화된 error UI를 생성하여 세분화하였다.
= app의 나머지 기능은 유지하면서 영향을 받는 세그먼트에 대한 오류만 영향을 받도록 하였다.
전체 페이지를 다시 로드하지 않고 오류에서 복구를 시도하는 기능을 추가했다.

How error.js Works

fallback error component가 활성화되면, error boundary 위에 laout은 상태와 interactive를 유지하며, error component는 오류를 복구(recover)하는 기능을 표시할 수 있다.

error.js는 중첩된 자식 세그먼트 또는 page.js 컴포넌트를 감싸는 React Error Boundary를 자동으로 생성한다.
error.js 파일에서 내보낸 React 컴포넌트가 fallback component으로 사용된다.
에러 경계 내에서 에러가 발생하면 에러가 포함된 fallback component가 렌더링된다.
fallback error component가 활성화되면 오류 경계 위의 레이아웃은 해당 상태를 유지하고 interactive 상태를 유지하며 error component는 recover 기능을 표시할 수 있다.

Recovering From Errors

오류의 원인은 일시적인 것일 수 있다. 이러한 경우 다시 시도하기만 하면 문제가 해결될 수 있다.

error component는 reset() 함수를 사용하여 사용자에게 오류에서 복구를 시도하라는 메시지를 표시할 수 있다. 이 함수가 실행되면 오류 경계의 내용을 다시 렌더링하려고 하고, 성공하면 fallback error component가 아닌 다시 렌더링한 결과로 바뀌게 된다.

error.tsx

'use client'
 
export default function Error({
  error,
  reset,
}: {
  error: Error
  reset: () => void
}) {
  return (
    <div>
      <h2>Something went wrong!</h2>
      <button onClick={() => reset()}>Try again</button>
    </div>
  )
}

Nested Routes

특수 파일(special files)을 통해 생성된 React component는 specific nested hierarchy로 렌더링된다.

예를 들어 layout.js, error.js 파일이 모두 포함된 두 개의 세그먼트가 있는 중첩된 경로는 다음과 같이 단순화된 컴포넌트 계층 구조로 렌더링된다:

nested-error-component-hierarchy

중첩된 컴포넌트 계층 구조는 중첩된 경로의 error.js 파일의 동작에 영향을 받는다.

오류는 가장 가까운 상위 error boundary까지 올라간다. 즉, error.js 파일은 중첩된 모든 하위 세그먼트에 대한 오류를 처리한다. 경로의 중첩된 폴더에 error.js 파일을 서로 다른 레벨에 배치하면 어느 정도 세분화된 오류 UI를 구현할 수 있다.
error boundary가 해당 Layout Component 안에 중첩되어 있기 때문에 error.js 경계는 동일한 세그먼트의 layout.js 컴포넌트에서 발생한 오류를 처리하지 않는다.

마지막 말이 뜻하는 바는 결국 layout.js가 error.js보다 밖에서 감싸고 있다고 생각해도 될 거 같다.

Handling Errors in Layouts

error.js boundaries는 같은 세그먼트의 layout.js 또는 template.js 컴포넌트에서 발생한 오류를 포착하지 못한다. intentional hierarchy는 오류가 발생했을 때 형제 경로(예: navigation) 간에 공유되는 UI가 계속 표시되고 작동하는게 더 중요하다.

특정 layout 또는 template 내에서 오류를 처리하려면 layout 상위 세그먼트에 error.js 파일에서 처리해야한다.

root layout 또는 template 내에서 오류를 처리하려면 global-error.js라는 error.js의 변형 파일을 만들어서 처리하면 된다.

Handling Errors in Root Layouts

root app/error.js boundary는 root app/layout.js 또는 app/template.js component에서 발생하는 오류를 포착하지 못한다.

이러한 root components의 오류를 구체적으로 처리하려면 root app directory에 있는 app/global-error.js라는 error.js의 변형을 사용해야한다.

root error.js와 달리 global-error.js error boundary는 전체 애플리케이션을 감싸며, 해당 fallback component가 활성화되면 root layout을 대체한다. 따라서 global-error.js는 자체 <html> 및 <body> 태그를 정의해야 한다.

glosbal-error.js는 가장 세분화된 오류 UI이며 전체 애플리케이션에 대한 "catch-all" 오류 처리로 간주할 수 있다. root components는 일반적으로 덜 동적이며 다른 error.js 경계가 대부분의 오류를 catch하므로 자주 트리거되지 않을 가능성이 높다.

global-error.js가 정의되어 있더라도 전역적으로 shared UI 및 branding을 포함하는 root layout내에서 렌더링될 fallback component가 있는 root error.js를 정의하는 것이 좋습니다.

Handling Server Errors

데이터 불러오기 또는 서버 컴포넌트 내부에서 오류가 발생하면 Next.js는 결과 오류 객체를 가장 가까운 error.js 파일에 오류 프로퍼티로 전달합니다.

next dev 실행할 때 오류가 직렬화되어, 서버 컴포넌트에서 client error.js로 전달됩니다. 프로덕션 환경에서 다음 시작을 실행할 때 보안을 보장하기 위해 일반 오류 메시지가 오류 메시지의 해시가 포함된 .digest와 함께 오류로 전달된다. 이 해시는 서버 로그에 대응하는 데 사용할 수 있습니다.

Reference

Next.js 13 - Error Handling