Next.js 13 App Router 마이그레이션하면서 꼭 확인한 체크리스트

Next.js 13의 App Router로 마이그레이션을 하면서 생각보다 삽질이 많았어요. 공식 문서만 보고 따라가면 놓치기 쉬운 부분들이 많더라고요. 그래서 직접 경험하며 정리한 체크리스트를 공유하려고 합니다.

이 글에서는 Next.js 13 App Router 마이그레이션에서 꼭 확인해야 할 항목들을 ✅체크리스트 형식으로 자세히 다뤄볼게요. 저처럼 막히는 분들께 조금이라도 도움이 되었으면 해요.

개발 환경 / 버전 정보

제가 작업한 환경은 다음과 같아요. 환경마다 미묘한 차이가 있으니 참고만 하시면 됩니다.

• Next.js 13.4.10 (App Router가 안정화된 버전 기준)
• Node.js 18.14.2
• React 18.3.0
• TypeScript 5.0.4 (선택사항)
• ESLint, Prettier 최신 버전 적용

Next.js 13 App Router 마이그레이션 핵심 체크리스트

사실 마이그레이션 과정에서 이 부분을 놓치면 꽤 난감해지더라고요. 제가 직접 겪으면서 꼭 체크했던 항목들이에요.

• 1. pages 디렉터리 → app 디렉터리 구조 변경
  App Router는 app 디렉터리 아래에 모든 라우트가 위치해요. 기존의 pages 디렉터리는 더 이상 사용하지 않는 점 꼭 확인하세요.
• 2. layout.tsx 파일 생성 필수 여부
  App Router는 자동으로 레이아웃을 병합하는 방식을 쓰는데 layout.tsx가 없으면 기본 레이아웃이 없어서 화면이 예기치 않게 깨질 수 있어요. 꼭 만들고 잘 적용되는지 확인하세요.
• 3. 서버 컴포넌트와 클라이언트 컴포넌트 구분
  App Router는 기본이 서버 컴포넌트입니다. 클라이언트에서만 동작하는 상태 관리나 이벤트가 있으면 'use client' 지시어를 넣어줘야 해요. 빠뜨리면 렌더링 에러가 납니다.
• 4. API 라우트 위치 변경
  app/api 디렉터리로 옮겨야 하고 각 파일은 route.ts로 분리해야 해요. 기존의 pages/api 라우트와 달라서 주의가 필요합니다.
• 5. 데이터 패칭 방식 변경
  App Router는 기본이 서버 컴포넌트라서 fetch가 직접 가능하고, React 18의 async/await 사용이 훨씬 자연스러워졌어요. 대신 getServerSideProps, getStaticProps는 더 이상 안 써요.

구현 중 실제 코드 예시

서버 컴포넌트 안에서 fetch를 이렇게 썼더니 편리했어요. 특히 async 함수로 바로 페이지 컴포넌트를 만들 수 있으니 코드가 훨씬 깔끔해졌습니다.

export default async function Home() {
  // 서버 컴포넌트에서는 fetch가 서버에서 실행돼서 보안에도 좋아요.
  const res = await fetch('https://api.example.com/posts', { cache: 'no-store' });
  const posts = await res.json();

  return (
    <main>
      <h1>포스트 목록</h1>
      <ul>
        {posts.map(post => (
          <li key={post.id}>{post.title}</li>
        ))}
      </ul>
    </main>
  );
}

이때 꼭 cache: 'no-store' 옵션이나 필요한 캐싱 전략을 직접 써주는 게 중요해요. 기본값은 캐싱이 가능해서 개발 중 데이터 갱신이 안 되는 문제로 헤맸거든요.

마이그레이션할 때 여기서 많이 틀립니다

막상 해보면 다음 두 가지가 가장 많이 헷갈리더라고요.

• 기존 getStaticProps나 getServerSideProps를 아직도 쓰려고 한다.
• 클라이언트 컴포넌트에 'use client'를 빼먹어 발생하는 렌더링 오류.

특히 후자는 초기 마이그레이션 때 자주 나타나서 브라우저 콘솔에 "Client component rendered on server" 같은 에러 메시지가 뜹니다. "아, 클라이언트임을 명확히 선언해줘야 하는구나" 하고 알게 되었어요.

이렇게 하면 마이그레이션 부담 줄어요

마이그레이션 전에는 프로젝트를 크게 나눠서 한 번에 모든 걸 바꾸려 하다가 고생했어요. 그래서 저는 다음과 같은 방식을 썼습니다.

• 기존 pages 디렉터리 유지하며 App Router 테스트용 app 디렉터리 병행 구성
• 라우터별로 점진적 이전
• 공통 레이아웃과 헤더, 푸터는 app/layout.tsx에서 관리

이 방법 덕분에 전체 구조를 한꺼번에 뜯지 않고 부분별로 점검하며 넘어가서 훨씬 안정적으로 작업할 수 있었어요.

자주 물어보시는 것들

Q. 기존 pages/api와 app/api를 둘 다 쓸 수 있나요?

A. 네, Next.js는 중복 지원하지만 권장하지는 않아요. 점진적 마이그레이션 단계에서 잠깐 병행하는 건 문제없지만 앱 전체가 app 디렉터리 기반이면 통일하는 게 관리하기 좋아요.

Q. use client를 어디에 붙여야 할지 감이 안 와요.

A. 보통 이벤트 핸들러, 상태관리(useState, useEffect 등)를 사용하는 컴포넌트 최상단에 'use client'를 붙여야 해요. 만약 하위 컴포넌트도 클라이언트 컴포넌트면 각각 붙일 필요는 없고 가장 상위 컴포넌트에만 붙이면 됩니다.

Q. App Router에서 CSS 모듈은 어떻게 처리되나요?

A. App Router에서도 CSS 모듈과 전역 CSS 방식을 기본적으로 지원합니다. 다만 app/layout.tsx나 app/page.tsx에 전역 스타일을 import하는 게 일반적이에요.

처음에는 새 구조가 낯설고 막히는 부분도 많지만, 이 체크리스트대로 하나씩 챙기면 예상보다 훨씬 수월하게 넘어갈 수 있을 거예요. Next.js 13 App Router 덕분에 코드가 훨씬 깔끔해진 점도 분명 느낄 수 있었고요.

마이그레이션할 때 이 글에서 꼭 체크한 항목들을 한번 더 확인해보시면서 작업해보세요. 큰 삽질 줄일 수 있을 겁니다.