🚀 Next.js Pages Router에서 App Router로 마이그레이션 가이드

Next.js 13부터 도입된 App Router는 기존 Pages Router보다 더 모듈화되고 유연한 구조를 제공합니다. 이 가이드는 기존 프로젝트를 App Router로 점진적으로 이전하는 방법을 단계별로 설명합니다.

✅ 1단계: app 디렉토리 생성

App Router는 app/ 디렉토리를 중심으로 작동합니다.

mkdir app

또는 src/ 디렉토리 내에 생성:

mkdir src/app

✅ 2단계: 루트 레이아웃 생성

모든 페이지에 공통으로 적용되는 app/layout.tsx를 생성합니다.

// app/layout.tsx
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="ko">
      <body>{children}</body>
    </html>
  );
}

_app.tsx, _document.tsx는 이제 사용하지 않습니다.

✅ 3단계: 페이지 이전

기존 pages 디렉토리의 파일을 app 디렉토리로 옮깁니다.

이전 위치 새로운 위치

pages/index.tsx	app/page.tsx
pages/about.tsx	app/about/page.tsx

폴더 구조가 곧 URL이 되며, 각 경로에는 page.tsx가 필요합니다.

✅ 4단계: 메타데이터 설정

App Router에서는 next/head 대신 metadata 객체를 사용합니다.

// app/page.tsx
export const metadata = {
  title: '홈페이지',
  description: 'Next.js App Router 예제',
};

export default function Page() {
  return <h1>환영합니다!</h1>;
}

✅ 5단계: 데이터 페칭 변경

getStaticProps, getServerSideProps 대신 **서버 컴포넌트 내 fetch**를 직접 사용합니다.

async function getPosts() {
  const res = await fetch('https://api.example.com/posts');
  return res.json();
}

export default async function PostsPage() {
  const posts = await getPosts();
  return (

{post.title}

  );
}

✅ 6단계: 라우팅 훅 변경

next/router에서 가져오던 useRouter 대신 아래를 사용합니다.

import { useRouter } from 'next/navigation';

✅ 7단계: 점진적 이전 가능

App Router와 Pages Router는 동시에 공존할 수 있으므로, 전체를 한 번에 마이그레이션할 필요는 없습니다. 중요한 페이지부터 순차적으로 이전하세요.

✅ 8단계: 에러 페이지 구성

app/error.tsx → 런타임 에러 처리
app/not-found.tsx → 404 처리

// app/error.tsx
'use client';
export default function Error() {
  return <h2>에러가 발생했습니다.</h2>;
}

// app/not-found.tsx
export default function NotFound() {
  return <h2>페이지를 찾을 수 없습니다.</h2>;
}

✅ 9단계: API 라우트 변경

App Router에서는 pages/api 대신 app/api 디렉토리를 사용합니다.

// app/api/hello/route.ts
export async function GET() {
  return new Response('안녕하세요!');
}

✅ 10단계: 글로벌 스타일 및 상태관리

글로벌 CSS는 globals.css로 유지하고 layout.tsx에서 import합니다.

// app/layout.tsx
import './globals.css';

상태 관리 라이브러리는 use client를 붙인 Provider로 wrapping 합니다.

// app/providers.tsx
'use client';
import { Provider } from 'react-redux';
import { store } from './store';

export function Providers({ children }: { children: React.ReactNode }) {
  return <Provider store={store}>{children}</Provider>;
}

그리고 layout에서 사용:

import { Providers } from './providers';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="ko">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

✅ 요약 비교표

항목 Pages Router App Router

디렉토리 구조	pages/	app/
공통 레이아웃	_app.tsx / _document.tsx	layout.tsx
데이터 페칭	getStaticProps 등	fetch (서버 컴포넌트)
메타데이터	next/head	metadata 객체
API 라우트	pages/api/	app/api/ (route.ts)
에러 핸들링	_error.tsx / 404.tsx	error.tsx / not-found.tsx

Next.js, App Router, 마이그레이션, pages 디렉토리, layout 구성, 서버 컴포넌트, metadata 설정, API route, 에러 페이지, 전역 상태 관리, 글로벌 스타일링, 점진적 이전, Next 13+ 구조