Next.js App Router 마이그레이션 완벽 가이드

• Next.js 버전이 13.4 이상인지 확인
• React 버전이 18.2.0 이상인지 확인
• TypeScript 사용 시 5.0 이상 권장
• 현재 사용 중인 모든 외부 라이브러리 목록 작성
• API 라우트 사용 현황 파악하기
• Git 브랜치 생성해서 안전하게 작업 진행

app/
├── layout.js          # 루트 레이아웃
├── page.js            # 홈페이지 (/)
├── loading.js         # 로딩 UI
├── error.js           # 에러 UI
├── not-found.js       # 404 페이지
│
├── blog/
│   ├── layout.js      # 블로그 전용 레이아웃
│   ├── page.js        # 블로그 메인 (/blog)
│   └── [slug]/
│       └── page.js    # 블로그 포스트 (/blog/post-1)
│
└── api/
    └── users/
        └── route.js   # API 엔드포인트

폴더 이름 앞에 언더스코어(_)를 붙이면 라우팅에서 제외돼요. 공용 컴포넌트, 유틸 함수 같은 거 정리하기 딱 좋죠.

app/
├── _components/       # 라우트 아님!
│   ├── Header.js
│   └── Footer.js
├── _utils/           # 라우트 아님!
│   └── helpers.js
└── page.js           # / 경로

괄호로 감싸면 URL에는 안 나오지만 그룹으로 묶을 수 있어요. 다른 레이아웃 적용할 때 진짜 유용해요.

app/
├── (marketing)/       # URL에 안 나타남
│   ├── layout.js     # 마케팅용 레이아웃
│   ├── page.js       # / 경로
│   └── about/
│       └── page.js   # /about 경로
│
└── (shop)/           # URL에 안 나타남
    ├── layout.js     # 쇼핑몰용 레이아웃
    └── products/
        └── page.js   # /products 경로

병렬 라우트와 인터셉팅 라우트는 진짜 강력하지만 처음엔 좀 어려울 수 있어요. 기본적인 App Router 구조에 먼저 익숙해진 다음에 천천히 적용해보세요. 서두르지 마시고요!

• 번들 사이즈 감소 - 클라이언트로 전송되는 JavaScript가 줄어들어요
• 직접 데이터 접근 - 데이터베이스나 파일 시스템에 바로 접근할 수 있죠
• 보안성 향상 - API 키나 민감한 로직을 서버에만 둘 수 있어요
• 캐싱 효율 - 서버에서 렌더링 결과를 캐싱해서 성능이 좋아져요
• 초기 로딩 속도 - HTML이 완성되어 전송되니까 빨라요

• useState, useReducer 같은 상태 관리 훅
• useEffect, useLayoutEffect 같은 생명주기 훅
• onClick, onChange 같은 이벤트 핸들러
• 브라우저 전용 API (window, document 등)
• 클라이언트 전용 라이브러리들

'use client'

import { useState } from 'react'

export default function Counter() {
  const [count, setCount] = useState(0)
  
  return (
    <button onClick={() => setCount(count + 1)}>
      클릭 수: {count}
    </button>
  )
}

1. 가능한 한 아래쪽에 배치 - 컴포넌트 트리에서 필요한 부분만 Client Component로 만드세요
2. 작게 쪼개기 - 버튼이나 인풋 같은 작은 단위로 분리하면 좋아요
3. children props 활용 - Server Component를 props로 넘겨서 조합할 수 있어요
4. 정적 콘텐츠는 분리 - 인터랙션 없는 부분은 Server Component로 두세요

// app/page.tsx (Server Component)
import ClientButton from './ClientButton'

export default async function Page() {
  // 서버에서 데이터 가져오기
  const data = await fetch('https://api.example.com/data')
  const posts = await data.json()
  
  return (
    <div>
      <h1>게시글 목록</h1>
      {posts.map(post => (
        <article key={post.id}>
          <h2>{post.title}</h2>
          <p>{post.content}</p>
          {/* Client Component는 여기서만 */}
          <ClientButton postId={post.id} />
        </article>
      ))}
    </div>
  )
}

• Server Component에서 useState 사용 - "React Hook useState cannot be called in a Server Component" 에러가 떠요
• Client Component에서 async 함수 직접 호출 - 데이터 페칭 방식이 달라요
• 모든 컴포넌트에 'use client' 추가 - Pages Router처럼 쓰려고 하면 안 돼요
• Server Component를 Client Component로 import - 자동으로 Client가 되버려요

// pages/posts/[id].js
export async function getServerSideProps({ params }) {
  const res = await fetch(`https://api.example.com/posts/${params.id}`)
  const post = await res.json()
  
  return {
    props: { post }
  }
}

export default function Post({ post }) {
  return 
{post.title}
}

// app/posts/[id]/page.js
async function getPost(id) {
  const res = await fetch(`https://api.example.com/posts/${id}`)
  return res.json()
}

export default async function Post({ params }) {
  const post = await getPost(params.id)
  
  return 
{post.title}
}

// 1. 정적 데이터 (기본값)
const staticData = await fetch('https://api.example.com/config')

// 2. 실시간 데이터
const realtimeData = await fetch('https://api.example.com/live', {
  cache: 'no-store'
})

// 3. ISR (1분마다 재생성)
const isrData = await fetch('https://api.example.com/posts', {
  next: { revalidate: 60 }
})

// 4. 태그 기반 캐싱
const taggedData = await fetch('https://api.example.com/products', {
  next: { tags: ['products'] }
})

// pages/posts/[id].js
export async function getStaticPaths() {
  const res = await fetch('https://api.example.com/posts')
  const posts = await res.json()
  
  const paths = posts.map(post => ({
    params: { id: post.id.toString() }
  }))
  
  return {
    paths,
    fallback: false
  }
}

export async function getStaticProps({ params }) {
  const res = await fetch(`https://api.example.com/posts/${params.id}`)
  const post = await res.json()
  
  return { props: { post } }
}

// app/posts/[id]/page.js
export async function generateStaticParams() {
  const posts = await fetch('https://api.example.com/posts').then(res => res.json())
  
  return posts.map(post => ({
    id: post.id.toString()
  }))
}

async function getPost(id) {
  const res = await fetch(`https://api.example.com/posts/${id}`)
  return res.json()
}

export default async function Post({ params }) {
  const post = await getPost(params.id)
  return 
{post.title}
}

export default async function Dashboard() {
  // 이렇게 하면 총 3초 걸려요
  const user = await fetch('/api/user')      // 1초
  const posts = await fetch('/api/posts')    // 1초
  const comments = await fetch('/api/comments') // 1초
  
  return 
...
}

export default async function Dashboard() {
  // 이렇게 하면 1초만 걸려요!
  const [user, posts, comments] = await Promise.all([
    fetch('/api/user'),
    fetch('/api/posts'),
    fetch('/api/comments')
  ])
  
  return 
...
}

'use client'

import { useState, useEffect } from 'react'

export default function UserProfile({ userId }) {
  const [user, setUser] = useState(null)
  
  useEffect(() => {
    fetch(`/api/users/${userId}`)
      .then(res => res.json())
      .then(data => setUser(data))
  }, [userId])
  
  if (!user) return 
Loading...
  
  return 
{user.name}
}

// app/posts/loading.js
export default function Loading() {
  return (
    

      

      

      

    
  )
}

'use client'

export default function Error({ error, reset }) {
  return (
    

      
문제가 발생했어요!
      
{error.message}
       reset()}>다시 시도
    
  )
}

가장 흔한 원인은 Date, Math.random(), localStorage 같은 서버와 클라이언트에서 다른 값을 반환하는 함수들이에요. 이런 거 사용할 땐 정말 조심해야 해요!

// ❌ 잘못된 방법
export default function Page() {
  return 
{new Date().toISOString()}
}

// ✅ 올바른 방법
'use client'
import { useState, useEffect } from 'react'

export default function Page() {
  const [date, setDate] = useState('')
  
  useEffect(() => {
    setDate(new Date().toISOString())
  }, [])
  
  return 
{date}
}

// Pages Router 방식
import dynamic from 'next/dynamic'

const Chart = dynamic(() => import('../components/Chart'), {
  ssr: false
})

// App Router 방식
import dynamic from 'next/dynamic'

const Chart = dynamic(() => import('../components/Chart'), {
  ssr: false,
  loading: () => 
Loading...
})

// 또는 더 명확하게
'use client'
import dynamic from 'next/dynamic'

const Chart = dynamic(() => import('../components/Chart'))

// Pages Router
pages/blog/[slug].js → /blog/:slug

// App Router
app/blog/[slug]/page.js → /blog/:slug

// Catch-all Routes
pages/shop/[...slug].js → /shop/*
app/shop/[...slug]/page.js → /shop/*

// Optional Catch-all
pages/docs/[[...slug]].js → /docs/* (including /docs)
app/docs/[[...slug]]/page.js → /docs/* (including /docs)

에러 메시지 그대로 구글에 검색하지 마세요! "Next.js 13 App Router"나 "Next.js 14" 키워드를 꼭 같이 넣으세요. 그냥 검색하면 Pages Router 해결법이 나와서 더 헷갈려요. 그리고 공식 GitHub Issues도 정말 유용해요. 비슷한 문제 겪은 사람들의 해결법이 많거든요.

• 기본적으로 모든 컴포넌트를 Server Component로 작성하세요
• 상호작용이 필요한 부분만 'use client'로 분리하세요
• 무거운 라이브러리는 가능한 서버 측에서만 사용하세요
• 데이터 fetching 로직을 Server Component로 옮기세요

// ❌ 최적화 전 - 전체가 클라이언트 컴포넌트
'use client'
import { format } from 'date-fns'
import { parseMarkdown } from 'marked'

export default function Article({ data }) {
  const [likes, setLikes] = useState(0)
  return (
    <div>
      <h1>{data.title}</h1>
      <p>{format(data.date, 'yyyy-MM-dd')}</p>
      <div dangerouslySetInnerHTML={{ __html: parseMarkdown(data.content) }} />
      <button onClick={() => setLikes(likes + 1)}>좋아요 {likes}</button>
    </div>
  )
}

// ✅ 최적화 후 - 상호작용 부분만 클라이언트로
// app/article/[id]/page.tsx (Server Component)
import { format } from 'date-fns'
import { parseMarkdown } from 'marked'
import LikeButton from './LikeButton'

export default async function ArticlePage({ params }) {
  const data = await getArticle(params.id)
  
  return (
    <div>
      <h1>{data.title}</h1>
      <p>{format(data.date, 'yyyy-MM-dd')}</p>
      <div dangerouslySetInnerHTML={{ __html: parseMarkdown(data.content) }} />
      <LikeButton initialLikes={data.likes} />
    </div>
  )
}

// app/article/[id]/LikeButton.tsx (Client Component)
'use client'
export default function LikeButton({ initialLikes }) {
  const [likes, setLikes] = useState(initialLikes)
  return <button onClick={() => setLikes(likes + 1)}>좋아요 {likes}</button>
}

// app/dashboard/page.tsx
import { Suspense } from 'react'
import UserInfo from './UserInfo'
import Analytics from './Analytics'
import RecentActivity from './RecentActivity'

export default function Dashboard() {
  return (
    <div>
      {/* 빠르게 로드되는 부분 */}
      <h1>대시보드</h1>
      
      {/* 사용자 정보는 빠르게 표시 */}
      <Suspense fallback={<UserSkeleton />}>
        <UserInfo />
      </Suspense>
      
      {/* 분석 데이터는 느리게 로드 */}
      <Suspense fallback={<AnalyticsSkeleton />}>
        <Analytics />
      </Suspense>
      
      {/* 최근 활동도 독립적으로 */}
      <Suspense fallback={<ActivitySkeleton />}>
        <RecentActivity />
      </Suspense>
    </div>
  )
}

// app/dashboard/Analytics.tsx
export default async function Analytics() {
  // 느린 API 호출
  const data = await fetch('https://api.example.com/analytics', {
    next: { revalidate: 3600 }
  })
  
  return <div>{/* 분석 데이터 렌더링 */}</div>
}

// 블로그 포스트 - 1시간마다 재검증
export async function getPosts() {
  const res = await fetch('https://api.example.com/posts', {
    next: { revalidate: 3600, tags: ['posts'] }
  })
  return res.json()
}

// 사용자 프로필 - 항상 최신 데이터
export async function getUserProfile(id: string) {
  const res = await fetch(`https://api.example.com/users/${id}`, {
    cache: 'no-store'
  })
  return res.json()
}

// 정적 페이지 콘텐츠 - 영구 캐싱
export async function getStaticContent() {
  const res = await fetch('https://api.example.com/static', {
    cache: 'force-cache'
  })
  return res.json()
}

// API 라우트에서 온디맨드 재검증
// app/api/revalidate/route.ts
import { revalidateTag } from 'next/cache'

export async function POST() {
  revalidateTag('posts')
  return Response.json({ revalidated: true })
}

import Image from 'next/image'

// ✅ 기본 사용법
<Image
  src="/hero.jpg"
  alt="히어로 이미지"
  width={1200}
  height={600}
  priority // LCP 이미지는 priority 설정
/>

// ✅ 외부 이미지 최적화
<Image
  src="https://example.com/photo.jpg"
  alt="외부 이미지"
  width={800}
  height={400}
  quality={85} // 기본값 75, 조정 가능
/>

// ✅ 반응형 이미지
<Image
  src="/banner.jpg"
  alt="배너"
  fill
  style={{ objectFit: 'cover' }}
  sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
/>

// ✅ 블러 플레이스홀더 (로컬 이미지)
<Image
  src={profilePic}
  alt="프로필"
  placeholder="blur"
/>

// ✅ 블러 플레이스홀더 (외부 이미지)
<Image
  src="https://example.com/photo.jpg"
  alt="외부 이미지"
  width={400}
  height={300}
  placeholder="blur"
  blurDataURL="data:image/jpeg;base64,..."
/>

• LCP 이미지에는 반드시 priority 속성 추가하세요
• sizes 속성으로 반응형 이미지 최적화하세요
• 외부 이미지는 next.config.js에 도메인 등록 필요해요
• 블러 플레이스홀더로 CLS(레이아웃 시프트) 방지하세요
• WebP 포맷은 자동으로 변환되니 걱정 없어요

import dynamic from 'next/dynamic'

// ✅ 무거운 차트 라이브러리 지연 로딩
const DynamicChart = dynamic(() => import('./Chart'), {
  loading: () => <p>차트 로딩 중...</p>,
  ssr: false // 클라이언트에서만 렌더링
})

// ✅ 모달은 필요할 때만 로드
const DynamicModal = dynamic(() => import('./Modal'))

export default function Dashboard() {
  const [showModal, setShowModal] = useState(false)
  
  return (
    <div>
      <h1>대시보드</h1>
      <DynamicChart data={chartData} />
      
      <button onClick={() => setShowModal(true)}>
        모달 열기
      </button>
      
      {showModal && <DynamicModal onClose={() => setShowModal(false)} />}
    </div>
  )
}

// ✅ 여러 컴포넌트를 하나의 청크로
const DynamicComponents = dynamic(() => 
  import('./HeavyComponents').then(mod => ({
    default: mod.ComponentA
  }))
)

// app/layout.tsx
import { Inter, Noto_Sans_KR } from 'next/font/google'

// Google 폰트 최적화
const inter = Inter({
  subsets: ['latin'],
  display: 'swap',
  variable: '--font-inter'
})

const notoSansKr = Noto_Sans_KR({
  subsets: ['latin'],
  weight: ['400', '700'],
  display: 'swap',
  variable: '--font-noto'
})

export default function RootLayout({ children }) {
  return (
    <html lang="ko" className={`${inter.variable} ${notoSansKr.variable}`}>
      <body>{children}</body>
    </html>
  )
}

// 로컬 폰트 사용하기
import localFont from 'next/font/local'

const myFont = localFont({
  src: [
    {
      path: './fonts/MyFont-Regular.woff2',
      weight: '400',
      style: 'normal',
    },
    {
      path: './fonts/MyFont-Bold.woff2',
      weight: '700',
      style: 'normal',
    }
  ],
  variable: '--font-my'
})

// app/layout.tsx
import { SpeedInsights } from '@vercel/speed-insights/next'
import { Analytics } from '@vercel/analytics/react'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <SpeedInsights />
        <Analytics />
      </body>
    </html>
  )
}

// 커스텀 리포팅
export function reportWebVitals(metric) {
  console.log(metric)
  
  // Google Analytics로 전송
  if (metric.label === 'web-vital') {
    window.gtag('event', metric.name, {
      value: Math.round(metric.value),
      event_label: metric.id,
      non_interaction: true,
    })
  }
}

• 개발 모드에서는 성능이 프로덕션보다 느려요
• 반드시 프로덕션 빌드로 테스트하세요
• 실제 사용자 환경에서 측정하는 게 가장 정확해요
• Lighthouse 점수만 보지 말고 실제 체감 속도도 확인하세요

1. Metadata 최적화
   generateMetadata로 SEO와 성능 둘 다 잡으세요
2. Route Prefetching 활용
   Link 컴포넌트는 자동으로 prefetch하니 적극 사용하세요
3. Parallel Routes로 동시 로딩
   여러 섹션을 병렬로 로드해서 속도 개선하세요
4. Intercepting Routes로 UX 개선
   모달이나 오버레이를 빠르게 표시할 수 있어요
5. Loading UI 전략적 배치
   loading.tsx를 적절한 위치에 두면 체감 속도가 빨라져요

import Link from 'next/link'

// 자동 prefetch (기본값)
<Link href="/dashboard">대시보드</Link>

// prefetch 비활성화 (필요할 때만)
<Link href="/heavy-page" prefetch={false}>
  무거운 페이지
</Link>

// 프로그래밍 방식 prefetch
import { useRouter } from 'next/navigation'

export default function MyComponent() {
  const router = useRouter()
  
  return (
    <button
      onMouseEnter={() => router.prefetch('/dashboard')}
      onClick={() => router.push('/dashboard')}
    >
      대시보드로 이동
    </button>
  )
}