Routing Files — 라우팅 파일 규칙

Next.js App Router는 9가지 특수 파일 이름을 인식합니다. 각 파일은 라우트 세그먼트 내에서 고유한 역할을 하며, 컴포넌트 계층 구조에서 정해진 순서로 중첩됩니다. 아래에서 각 파일의 동작을 직접 체험해보세요.

체험 가능한 파일

layout.tsx

하위 라우트를 감싸는 공유 UI. 네비게이션 간 상태가 유지됩니다.

loading.tsx

Suspense 기반 로딩 UI. 콘텐츠가 로드되는 동안 표시됩니다.

error.tsx

React Error Boundary. 해당 세그먼트의 에러를 잡아 폴백 UI를 표시합니다.

not-found.tsx

notFound() 호출 시 표시되는 커스텀 404 UI입니다.

template.tsx

layout과 유사하나 네비게이션마다 새 인스턴스가 생성됩니다.

route.ts

API 엔드포인트 핸들러. page.tsx 대신 HTTP 요청을 처리합니다.

코드 예시로 확인하는 파일

아래 파일들은 특수한 조건에서만 동작하므로 실시간 데모가 어렵습니다. 코드 예시로 역할을 확인하세요.

global-error.tsx

루트 레벨 전용 에러 바운더리입니다. 전체 앱의 치명적 에러를 처리하며, 활성화 시 루트 layout을 대체하므로 자체 <html>, <body> 태그를 포함해야 합니다. 프로덕션 빌드에서만 동작합니다.

'use client';

// app/global-error.tsx
const GlobalError = (props: {
  error: Error & { digest?: string };
  reset: () => void;
}) => {
  const { error, reset } = props;

  return (
    <html>
      <body>
        <h2>치명적 에러가 발생했습니다</h2>
        <p>{error.message}</p>
        <button onClick={() => reset()}>다시 시도</button>
      </body>
    </html>
  );
};

export default GlobalError;

default.tsx

병렬 라우트(Parallel Routes)에서 일치하는 슬롯이 없을 때 보여줄 폴백 페이지입니다. @slot 폴더 내에 배치하며, 소프트 네비게이션 시에는 이전 상태를 유지하지만 하드 리로드 시 이 파일이 렌더링됩니다.

// app/@analytics/default.tsx
// 병렬 라우트 슬롯의 폴백

const AnalyticsDefault = () => {
  return (
    <div>
      <p>분석 데이터를 불러오는 중입니다...</p>
    </div>
  );
};

export default AnalyticsDefault;

컴포넌트 중첩 순서 (Component Hierarchy)

<Layout>          ← layout.tsx (상태 유지)
  <Template>      ← template.tsx (매번 재생성)
    <ErrorBoundary>   ← error.tsx
      <Suspense fallback={<Loading />}>  ← loading.tsx
        <NotFound />  ← not-found.tsx
        <Page />      ← page.tsx
      </Suspense>
    </ErrorBoundary>
  </Template>
</Layout>

파일 구조

demo/nextjs/16.1.6/project-structure/routing-files/
|- page.tsx

핵심 파일 코드

// demo/nextjs/16.1.6/project-structure/routing-files/page.tsx
export default function Page() {
    // 핵심 동작: 실제 파일 구조와 런타임 결과를 함께 확인
}