Next.js App Router 학습 순서: 설치부터 배포까지

학습 목표·선수 지식: Next.js를 처음 설치하는 단계부터 App Router의 라우팅·컴포넌트 경계·데이터 상태·SEO·배포까지 한 흐름으로 익힙니다. 선수 지식: HTML·CSS·JavaScript, React 컴포넌트·props·state 기초.

0단계: 시작 전에 필요한 선수 지식

Next.js를 시작하기 전에 HTML·CSS·JavaScript와 React 컴포넌트, props, state, 이벤트 처리 정도는 익혀두는 것이 좋습니다. Next.js는 React를 대신하는 별도 문법이 아니라 React 애플리케이션에 라우팅, 서버 렌더링, 데이터 처리, 빌드·배포 규칙을 더하는 프레임워크이기 때문입니다.

처음부터 인증, 결제, 복잡한 전역 상태까지 넣을 필요는 없습니다. 이 글에서는 새 프로젝트를 직접 만들고 브라우저에서 실행한 뒤, 목록과 상세 화면이 있는 작은 블로그를 기준으로 App Router의 핵심 흐름을 연결합니다.

1단계: Node.js와 npm 실행 환경 확인하기

Next.js 프로젝트를 만들기 전에 터미널에서 Node.js와 npm이 실행되는지 먼저 확인합니다. 현재 이 글의 기준인 Next.js 16 App Router는 Node.js 20.9 이상을 사용합니다.

node -v
npm -v

node -v에서 20.9 이상의 버전이 나오고 npm -v도 정상적으로 버전 번호를 출력하면 다음 단계로 넘어가면 됩니다. 명령을 찾을 수 없다는 메시지가 나오면 Node.js 공식 사이트에서 LTS 버전을 설치한 뒤 터미널을 다시 열어 확인하세요.

npm과 package.json의 역할이 아직 익숙하지 않다면 프로젝트를 만든 뒤 Next.js package.json: scripts와 dependencies 이해를 이어서 확인하면 됩니다.

2단계: 첫 Next.js 프로젝트 만들기

작업할 폴더에서 다음 명령을 실행합니다. create-next-app은 Next.js 프로젝트에 필요한 기본 파일과 의존성, 개발 스크립트를 한 번에 구성하는 공식 CLI입니다.

npx create-next-app@latest my-next-app

설치 과정에서 몇 가지 선택 항목이 나오면 처음 학습할 때는 TypeScript와 App Router를 사용하는 구성을 권장합니다. 나머지 옵션은 프로젝트 목적에 따라 달라질 수 있으므로 모든 선택지를 외우기보다 생성된 폴더와 package.json, app 디렉터리가 무엇을 담당하는지 확인하는 편이 중요합니다.

명령이 끝나면 my-next-app 폴더가 생성됩니다. 이 폴더가 앞으로 코드를 작성하고 명령을 실행할 프로젝트 루트입니다.

3단계: 개발 서버 실행 확인하기

생성된 프로젝트 폴더로 이동한 뒤 개발 서버를 실행합니다.

cd my-next-app
npm run dev

브라우저에서 http://localhost:3000을 열었을 때 Next.js 기본 화면이 보이면 설치와 첫 실행이 완료된 것입니다. 여기까지 성공한 뒤에 라우팅과 Server Component 같은 개념을 공부하면 이후 예제를 바로 실행해볼 수 있습니다.

실행 확인까지 끝났다면 app/page.tsx의 제목 문구를 한 번 바꿔 저장해보세요. 브라우저 화면이 갱신되면 “파일 수정 → 개발 서버 반영 → 브라우저 확인”이라는 기본 개발 흐름까지 준비된 것입니다. 더 작은 완성 프로젝트로 직접 실습하려면 Next.js App Router로 만드는 첫 프로젝트 완성 실습 가이드를 이어서 진행하세요.

4단계: page와 layout으로 URL 구조 만들기

app/page.tsx는 루트 URL의 화면이고, 폴더 안의 page.tsx는 해당 경로의 화면입니다. layout.tsx는 여러 하위 페이지가 공유할 UI를 감쌉니다. 첫 단계에서는 홈, 글 목록, 글 상세 세 경로만 만들고 각 URL이 어떤 파일과 연결되는지 확인하면 됩니다.

app/
├─ layout.tsx
├─ page.tsx
└─ posts/
   ├─ page.tsx
   └─ [slug]/
      └─ page.tsx

완료 기준은 주소창에서 /, /posts, /posts/react-state를 열었을 때 의도한 페이지와 공통 레이아웃이 나오는 것입니다.

5단계: 동적 라우팅과 이동 처리하기

게시글처럼 데이터에 따라 URL이 달라지는 화면은 [slug] 동적 세그먼트로 만듭니다. 현재 App Router에서는 동적 route의 params를 Promise로 받아 기다린 뒤 값을 꺼내는 예제를 기준으로 익히는 편이 안전합니다.

app/posts/[slug]/page.tsx의 라우팅 부분 예제입니다. getPost는 프로젝트 서버 데이터 모듈에서 import하며 title을 반환합니다. 실제 완성본에는 null 결과의 notFound 처리도 필요합니다.

type PostPageProps = {
  params: Promise<{ slug: string }>;
};

export default async function PostPage({ params }: PostPageProps) {
  const { slug } = await params;
  const post = await getPost(slug);

  return <article>{post.title}</article>;
}

목록에서 상세 페이지로 이동할 때는 Link를 사용하고, 존재하지 않는 slug에는 notFound()와 not-found.tsx를 연결합니다. 동적 경로 자체가 헷갈리면 Next.js 동적 라우팅 사용법을 함께 확인하세요.

6단계: Server·Client Component 경계 잡기

App Router의 컴포넌트는 기본적으로 Server Component입니다. 서버에서 데이터를 읽고 HTML을 만드는 화면은 그대로 두고, 클릭 이벤트, 브라우저 API, useState가 필요한 작은 영역에만 'use client'를 적용합니다.

페이지 전체를 Client Component로 바꾸기 전에 “이 컴포넌트에 실제 상호작용이 필요한가?”를 먼저 확인하세요. 글 상세는 서버에서 읽고, 좋아요 버튼만 Client Component로 분리하는 식이 이해하기 쉽습니다. 완료 기준은 서버 전용 코드가 클라이언트 번들로 넘어가지 않고 상호작용 영역만 정상 동작하는 것입니다.

7단계: 데이터·로딩·오류 상태 연결하기

다음은 페이지에서 직접 데이터를 읽고, 느린 요청과 실패 상황을 화면으로 표현하는 단계입니다. loading.tsx, error.tsx, not-found.tsx의 역할을 구분하고, 필요한 경우 Suspense로 느린 영역만 나눕니다.

이 단계에서는 캐시 옵션을 모두 외울 필요가 없습니다. 먼저 같은 요청이 언제 다시 실행되는지 확인하고, 최신성이 중요한 데이터와 재사용 가능한 데이터를 구분하세요. 목록 로딩, 없는 게시글, 서버 오류를 각각 재현할 수 있으면 다음 단계로 넘어가도 됩니다.

8단계: metadata와 검색 노출 확인하기

정적 페이지는 metadata, 게시글처럼 URL마다 제목과 설명이 달라지는 페이지는 generateMetadata를 사용합니다. 본문을 가져오는 함수와 metadata의 데이터 요청이 중복되지 않는지도 확인합니다.

같은 app/posts/[slug]/page.tsx에 추가하는 부분 함수입니다. 앞의 PostPageProps 타입과 getPost 함수를 공유하고 반환 데이터에 summary를 준비합니다. 별도 파일에 이 함수만 복사하는 예제가 아닙니다.

export async function generateMetadata({ params }: PostPageProps) {
  const { slug } = await params;
  const post = await getPost(slug);

  return {
    title: post.title,
    description: post.summary,
  };
}

브라우저 탭만 보지 말고 실제 페이지 소스에 title, description, canonical과 주요 본문이 들어가는지 확인하세요. 전체 설정은 Next.js Metadata API 완전 정리와 Next.js SEO 완전 가이드에서 이어서 볼 수 있습니다.

9단계: 프로덕션 빌드와 배포 검증하기

로컬 개발 서버에서 보인다고 학습이 끝난 것은 아닙니다. 프로덕션 빌드를 실행해 타입·빌드 오류를 확인하고, 배포 URL에서 새로고침, 동적 상세 경로, 환경변수, 이미지, 404 화면, metadata를 다시 확인해야 합니다.

npm run build
npm run start

배포 후에는 홈에서 상세 페이지로 이동하는 경우와 상세 URL을 직접 여는 경우를 모두 시험하세요. 성능 점검은 기능과 검색 노출이 정상인 뒤 Next.js 성능 최적화 기준으로 확장하면 됩니다.

작은 프로젝트 완료 기준

• Node.js와 npm 버전을 직접 확인할 수 있다.
• create-next-app으로 새 프로젝트를 만들고 개발 서버를 실행할 수 있다.
• 홈·목록·동적 상세 URL이 각각 올바른 화면을 보여준다.
• 공통 layout과 페이지별 UI의 책임이 분리되어 있다.
• 상호작용이 필요한 영역만 Client Component로 구성했다.
• 로딩·오류·없는 데이터 상태를 직접 재현할 수 있다.
• 상세 페이지마다 title과 description이 달라진다.
• 프로덕션 빌드와 배포 URL에서 직접 접근·새로고침이 정상이다.

앞의 항목을 직접 확인할 수 있다면 App Router 기초를 끝낸 것입니다. 이후 인증, Server Functions, 캐싱과 재검증, 테스트를 프로젝트 요구에 맞춰 하나씩 추가하면 됩니다.

오류 상태를 일부러 만들어 완료 여부를 확인합니다

상태	실습 변경 위치	기대
느린 응답	로컬 데이터 함수의 Promise 대기	loading.tsx 또는 Suspense fallback
예상하지 못한 실패	page의 조회 함수에서 Error throw	가장 가까운 error.tsx
없는 글	조회 결과 null에서 notFound	not-found UI
다시 시도	error.tsx의 reset 버튼	경계 아래 렌더 재시도

app/posts/error.tsx · 전체 파일

"use client";
export default function ErrorView({
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  return (
    <section>
      <h2>글을 불러오지 못했습니다</h2>
      <button onClick={() => reset()}>다시 시도</button>
    </section>
  );
}

이 경계는 같은 segment의 layout 자체 오류를 잡지 못하므로 상위 경계가 필요합니다. reset은 실패 원인을 고치거나 서버 캐시를 자동 무효화하는 기능이 아닙니다. 위 파일은 기존 학습 프로젝트에 추가하며 정상 응답을 먼저 완성한 후 각 실패를 하나씩 실험합니다.

공식 문서

• Next.js Installation
• Next.js Layouts and Pages
• Next.js Server and Client Components
• Next.js Metadata and OG Images

공식 기준과 확인 범위

확인일: 2026-09-16. 실행 환경과 프로젝트 생성 흐름은 Next.js 16 App Router 공식 문서를 기준으로 재확인했습니다. API 설명은 Next.js 16 App Router 기준이며 과거 릴리스 글은 본문의 태그 범위를 유지합니다. 부분 API 코드는 기존 프로젝트에 통합하는 예시입니다.

• https://nextjs.org/docs/app/getting-started/installation
• https://nextjs.org/docs/app/api-reference/file-conventions/error

공식 자료 재확인: 2026-09-16. 이 글의 실행하지 않은 브라우저/배포 점검은 독자 확인 과제로 구분합니다.