🔄 Next.js App Router 업그레이드 가이드

Next.js App Router는 Pages Router 대비 훨씬 더 유연하고 확장성 높은 구조를 제공합니다.
기존 프로젝트를 최신 버전(App Router 기반)으로 업그레이드하는 방법을 단계별로 정리합니다.

✅ 1. Next.js 및 Node.js 버전 업데이트

Next.js: 최신 버전 설치 (13.4 이상)
Node.js: 최소 18.17 이상 필요

npm install next@latest react@latest react-dom@latest

추가로 ESLint 설정도 업데이트하면 좋습니다.

npm install -D eslint-config-next@latest

✅ 2. 새로운 기능 대응

📷 Image 컴포넌트 개선

더 이상 next/future/image가 필요 없습니다. 기본 next/image를 사용하세요.

import Image from 'next/image';

export default function Example() {
  return <Image src="/logo.png" width={500} height={300} alt="로고" />;
}

🔗 Link 컴포넌트 간소화

<a> 태그 없이 바로 사용할 수 있습니다.

import Link from 'next/link';

<Link href="/about">About</Link>

🧠 폰트 최적화 (next/font)

Google Fonts 또는 로컬 폰트를 간편하게 사용할 수 있습니다.

import { Inter } from 'next/font/google';

const inter = Inter({ subsets: ['latin'] });

export default function Page() {
  return <div className={inter.className}>폰트 적용 완료</div>;
}

✅ 3. App Router로 마이그레이션

📁 app 디렉토리 생성

루트에 app/ 폴더를 만들고, 모든 페이지와 레이아웃을 이곳에 구성합니다.

app/
  layout.tsx
  page.tsx
  about/
    page.tsx

🗂️ 레이아웃 설정

layout.tsx는 모든 하위 페이지에 공통 적용됩니다.

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

✅ 4. 데이터 패칭 구조 변경

기존 방식 (getServerSideProps, getStaticProps) 제거

App Router에서는 서버 컴포넌트 안에서 바로 fetch를 사용할 수 있습니다.

export default async function PostPage({ params }: { params: { id: string } }) {
  const res = await fetch(`https://api.example.com/posts/${params.id}`);
  const post = await res.json();

  return

{post.title}

;
}

generateStaticParams 사용 (SSG)

export async function generateStaticParams() {
  const posts = await fetch('https://api.example.com/posts').then(res => res.json());
  return posts.map((post: { id: string }) => ({ id: post.id }));
}

경로별 정적 생성을 위해 사용합니다.

✅ 5. 라우팅 훅 변경

Pages Router에서 사용하던 useRouter 대신 App Router 전용 훅을 사용합니다.

import { useRouter, usePathname, useSearchParams } from 'next/navigation';

const router = useRouter();
const pathname = usePathname();
const searchParams = useSearchParams();

✅ 6. 에러 및 Not Found 처리

에러 페이지

// app/error.tsx
'use client';

export default function Error({ error, reset }: { error: Error; reset: () => void }) {
  return (
    <div>
      <h1>문제가 발생했습니다.</h1>
      <button onClick={() => reset()}>다시 시도</button>
    </div>
  );
}

404 페이지

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

✅ 7. 스타일링

전역 스타일은 layout.tsx에 import 합니다.

import './globals.css';

Tailwind CSS 같은 것도 그대로 적용 가능합니다.

🧠 핵심 체크리스트

항목 내용

Node.js	18.17 이상
Next.js	13.4 이상
app/ 디렉토리 사용	page.tsx, layout.tsx 중심
데이터 패칭	서버 컴포넌트 + fetch 기반
에러 처리	error.tsx, not-found.tsx 추가
SEO/OG 설정	metadata 객체 활용 가능

https://nextjs.org/docs/app/getting-started/upgrading

Next.js, App Router, 업그레이드, 마이그레이션, 데이터 패칭, 서버 컴포넌트, 에러 처리, 라우팅 변경, SEO 최적화, App Directory