Next.js App Router 학습 순서와 TaskFlow Next.js 시작

React 기초를 아는 개발자는 Next.js App Router를 어떤 순서로 배우나요?

React의 props·state·이벤트를 안다면 Next.js는 폴더와 URL 연결, 서버와 브라우저의 실행 경계부터 시작합니다. 작은 페이지를 만든 뒤 데이터·인증·캐시로 확장합니다.

적용 조건·범위: 이 과정은 App Router를 기준으로 합니다. pages 디렉터리와 getServerSideProps 예제를 그대로 가져오지 않습니다.

본문 근거: Next.js Installation · Next.js App Router

Next.js는 무엇을 추가할까

React만으로도 SPA를 만들 수 있습니다. 하지만 실제 서비스에서는 다음 문제가 생깁니다.

URL마다 다른 화면을 어떻게 연결할까
첫 HTML을 서버에서 어떻게 만들까
서버에서만 실행해야 하는 코드는 어디에 둘까
데이터를 어떻게 캐시하고 갱신할까
검색엔진용 metadata는 어떻게 만들까
API와 mutation은 어디에서 처리할까

Next.js는 이 문제를 프레임워크 수준에서 다룹니다.

38회차 학습 순서

초급

첫 실행과 과정 안내
App Router 기본 프로젝트
package.json
Server / Client Component
.next 빌드 산출물
Route Group · Private Folder · template
Parallel Routes
Intercepting Routes
동적 라우트
async params
loading / error / not-found
window is not defined
hydration
Server Component 데이터 조회·Streaming

중급

MSW Mock API
Axios
Route Handler
Server Actions
Auth.js
인증·Proxy
useSearchParams
fetch cache
TanStack Query SSR/Hydration
cookies / headers
환경변수
Metadata
metadata 오류
Image remotePatterns
redirects

고급

Request/Data/Full Route/Router Cache
SEO 체크리스트
SEO 종합
성능 체크
렌더링 성능
Proxy 마이그레이션
보안 패치
초기 HTML·SSR SEO
캐시 API·버전 변화 대응

개발환경 확인

터미널에서 다음 명령을 실행합니다.

node -v
npm -v

둘 다 버전이 출력되어야 합니다.

Next.js와 create-next-app의 요구 Node.js 버전은 바뀔 수 있으므로 실제 게시 시점에는 공식 문서를 다시 확인합니다.

독립 연습 프로젝트 생성

아래 생성 명령의 taskflow-next는 연습 폴더 이름입니다. 기본 프로젝트를 만든 뒤 /practice 파일을 추가하는 상단 실습에는 완료 ZIP이 필요 없습니다. 생성 버전은 원문의 16.3.5로 두고 자신의 Node.js와 설치 결과를 확인합니다.

npx create-next-app@16.3.5 taskflow-next --ts --app --no-tailwind --no-src-dir --import-alias "@/*"
cd taskflow-next
npm run dev

create-next-app 질문에서는 TypeScript와 App Router를 사용하는 구성을 선택합니다.

예시:

TypeScript: Yes
ESLint: Yes
Tailwind CSS: No
src/ directory: No
App Router: Yes
import alias: 기본값 사용 가능

브라우저에서 개발 서버 주소를 열어 생성된 기본 Next.js 화면을 확인합니다. 하단 완료 체크포인트의 TaskFlow 홈 화면과는 파일 내용이 다릅니다.

자주 발생하는 오류

node 또는 npm 명령을 찾을 수 없습니다

Node.js 설치와 PATH를 먼저 확인합니다.

포트가 이미 사용 중입니다

Next.js가 다른 포트를 사용하도록 실행할 수 있습니다.

npm run dev -- -p 3001

Pages Router 예제와 App Router 예제가 섞입니다

이 과정은 App Router를 기준으로 합니다. pages 디렉터리와 getServerSideProps 예제를 그대로 가져오지 않습니다.

독립 실습: 폴더로 새 URL 만들기

원래 첫 페이지 컴포넌트의 표시 결과를 확인하세요.

예제 크게 보기 (새 탭)

위에서 만든 Next.js 프로젝트에서 app/practice/page.tsx 파일을 새로 만듭니다. TaskFlow ZIP은 필요 없습니다.

export default function PracticePage() {
  return (
    <main>
      <h1>내 첫 App Router 페이지</h1>
      <p>이 화면은 /practice 경로에서 열립니다.</p>
    </main>
  );
}

npm run dev를 실행한 뒤 개발 서버 주소 뒤에 /practice를 붙여 엽니다. 예를 들어 서버가 http://localhost:3000이면 http://localhost:3000/practice입니다. 기대 결과는 제목과 문장이 보이는 것입니다. app/page.tsx는 / 경로, app/practice/page.tsx는 /practice 경로를 담당합니다.

스스로 확인: 폴더를 app/notes/로 옮기면 어느 URL을 열어야 할까요? 답은 /notes입니다. 새 경로가 열리지 않으면 파일명이 page.tsx인지, app 폴더 안인지, 터미널에 컴파일 오류가 있는지 확인하세요.

학습 완료 체크리스트

Next.js가 React 위에서 해결하는 문제를 설명할 수 있다
App Router와 Pages Router를 구분할 수 있다
create-next-app으로 TypeScript 프로젝트를 만들 수 있다
npm run dev로 첫 화면을 띄울 수 있다
앞으로 어떤 순서로 학습하는지 설명할 수 있다

선택 실습: 할 일 앱에 적용하기

TaskFlow는 작업을 추가·완료·삭제하는 할 일 앱입니다. 이 선택 실습에서는 Next.js로 페이지와 서버 기능을 확장합니다.

새 Next.js 프로젝트를 만들고 React에서 익힌 작업 모델을 App Router 구조로 다시 옮깁니다. React ZIP의 모든 UI 라이브러리를 그대로 복사하는 방식은 아닙니다.

선택: 연재 프로젝트와 전체 자료

연재 프로젝트를 이어 만드는 분을 위한 자료입니다. 이 글의 개념과 예제만 찾으셨다면 필요한 파일과 실행 방법만 펼쳐보세요.

TaskFlow Next.js 프로젝트 적용

TaskFlow Next.js 첫 빌드 화면

원본 첫 단계에서 실제 정적 빌드한 제목과 소개 문구를 확인하세요.

예제 크게 보기 (새 탭)

시작 체크포인트: 새 프로젝트에서 시작합니다. 이전: Next.js로 TaskFlow 만들기: 38편 학습 과정 미리보기는 과정 안내이며 이전 완료 코드가 필요한 단계는 아닙니다.

이번 체크포인트에 포함되는 파일: .gitignore, app/globals.css, app/layout.tsx, app/page.tsx, next-env.d.ts, next.config.ts, package.json, tsconfig.json. 아래 변경 설명을 따라 수정하고 전체 코드의 같은 파일과 대조합니다.

완료 코드 ZIP 다운로드 — next-step-01-first-run

이전 체크포인트: 새 프로젝트

이번 회차의 변경

새 Next.js 프로젝트를 만들고 React에서 익힌 작업 모델을 App Router 구조로 다시 옮깁니다. React ZIP의 모든 UI 라이브러리를 그대로 복사하는 방식은 아닙니다. 루트 app/ 구조와 일반 CSS를 사용합니다.

기대 결과: 완료 체크포인트의 app/page.tsx와 app/layout.tsx를 연결하면 /에서 TaskFlow Next.js 제목과 소개 문장이 표시됩니다. 상단 독립 예제의 /practice는 직접 추가한 연습 경로이며 완료 ZIP에 포함된 것으로 가정하지 않습니다. 설치·개발 서버·빌드·브라우저 실행은 이번 편집에서 수행하지 않았으므로 이 결과는 코드 기준 기대값입니다.

변경·추가 파일:

app/page.tsx
app/layout.tsx

전체 파일·코드 보기

실행과 검증

Node.js 22 LTS 이상 권장(Next.js 최소 20.9). 루트 app/ 구조, CSS 사용.

npm install
npm run dev
npm run build
npm run start

전체 코드와 ZIP은 같은 완료 체크포인트입니다. 자동 생성 worker는 ZIP에 포함하며 라이브러리 파일은 코드 뷰어에서 생략합니다.

완료 체크포인트: next-step-01-first-run

실습 프로젝트 전체 코드

.gitignore

node_modules
.next
.env*
!.env.example
*.tsbuildinfo

app/globals.css

* {
  box-sizing: border-box;
}
body {
  margin: 0;
  color: #171717;
  background: #fafafa;
  font-family: Arial, sans-serif;
  line-height: 1.6;
}
header,
main {
  width: min(880px, calc(100% - 32px));
  margin: 24px auto;
}
nav {
  display: flex;
  flex-wrap: wrap;
  gap: 16px;
  align-items: center;
}
a {
  color: inherit;
  text-underline-offset: 3px;
}
button,
input,
select {
  min-height: 44px;
  padding: 8px 12px;
  font: inherit;
  border: 1px solid #aaa;
  background: #fff;
  color: #171717;
  max-width: 100%;
}
button {
  cursor: pointer;
}
button:disabled {
  opacity: 0.6;
  cursor: wait;
}
input {
  display: block;
  width: 100%;
}
label {
  display: block;
}
form,
section,
aside {
  margin: 20px 0;
}
ul {
  padding: 0;
  list-style: none;
}
li {
  padding: 12px;
  margin: 12px 0;
  border: 1px solid #ccc;
  overflow-wrap: anywhere;
}
.controls {
  display: flex;
  flex-wrap: wrap;
  gap: 8px;
  align-items: center;
}
.controls form {
  margin: 0;
}
.modal {
  width: min(640px, calc(100% - 32px));
  border: 1px solid #777;
  padding: 24px;
  background: #fff;
  color: #171717;
}
.modal::backdrop {
  background: rgb(0 0 0 / 55%);
}
:focus-visible {
  outline: 3px solid #555;
  outline-offset: 3px;
}
[data-theme="dark"] {
  background: #202020;
  color: #fafafa;
  padding: 16px;
}
[data-density="compact"] li {
  padding: 8px;
  margin: 8px 0;
}
img {
  max-width: 100%;
  height: auto;
}

app/layout.tsx

import type { Metadata } from "next";
import type { ReactNode } from "react";
import "./globals.css";
export const metadata: Metadata = {
  title: { default: "TaskFlow Next.js", template: "%s | TaskFlow" },
  description: "서버와 브라우저 역할을 배우는 TaskFlow 학습 프로젝트",
};
export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="ko">
      <body>{children}</body>
    </html>
  );
}

app/page.tsx

export default function HomePage() {
  return (
    <main>
      <p>Next.js Learning Project</p>
      <h1>TaskFlow Next.js</h1>
      <p>React TaskFlow를 Next.js 서비스로 확장합니다.</p>
    </main>
  );
}

next-env.d.ts

/// <reference types="next" />
/// <reference types="next/image-types/global" />
import "./.next/types/routes.d.ts";
import "./.next/types/root-params.d.ts";


// NOTE: This file should not be edited
// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

next.config.ts

import type { NextConfig } from "next";
const config: NextConfig = { cacheComponents: false };
export default config;

package.json

{
  "name": "taskflow-next",
  "version": "1.0.1",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "build": "next build --webpack",
    "start": "next start",
    "typecheck": "tsc --noEmit"
  },
  "dependencies": {
    "next": "16.3.5",
    "react": "19.3.0",
    "react-dom": "19.3.0"
  },
  "devDependencies": {
    "typescript": "5.9.3",
    "@types/node": "24.13.6",
    "@types/react": "19.3.0",
    "@types/react-dom": "19.3.0"
  }
}

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": [
      "dom",
      "dom.iterable",
      "esnext"
    ],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "react-jsx",
    "incremental": true,
    "plugins": [
      {
        "name": "next"
      }
    ],
    "paths": {
      "@/*": [
        "./*"
      ]
    }
  },
  "include": [
    "next-env.d.ts",
    "**/*.ts",
    "**/*.tsx",
    ".next/types/**/*.ts",
    ".next/dev/types/**/*.ts"
  ],
  "exclude": [
    "node_modules"
  ]
}

글 소개·학습 준비·전체 목차

App Router 단계: page·layout, 동적 라우팅, 컴포넌트 경계

Next.js · 1/38 · TaskFlow 누적 실습

Next.js App Router 학습 순서와 TaskFlow Next.js 시작

Next.js · 1 / 38 · 필수 길잡이 · App Router 시작

React 컴포넌트의 입력·상태·이벤트를 알고 있다면, Next.js의 파일 기반 라우팅과 서버 실행 경계를 작은 화면부터 확인할 수 있습니다.

이 과정은 Next.js 문법을 따로 외우는 데서 끝나지 않습니다. React TaskFlow를 Next.js 기반 서비스로 옮기고, 38회에 걸쳐 라우팅·데이터·인증·캐시·SEO·성능·운영 구조를 단계적으로 확장합니다.

이번 글에서 배우는 내용

Next.js가 React에 추가하는 역할
App Router 기준 학습 순서
Node.js와 npm 확인
create-next-app으로 TypeScript 프로젝트 생성
npm run dev 첫 실행
38회차 TaskFlow Next.js 전체 흐름

선수 지식

이 과정은 React 기초 과정을 마쳤다고 가정합니다.

최소한 다음 내용을 읽고 수정할 수 있어야 합니다.

컴포넌트와 JSX
props와 state
이벤트 처리
useEffect와 Client Component의 의미
TypeScript 기본 타입
import/export

다음 학습

다음 글에서는 기본 프로젝트의 app 디렉터리, layout.tsx, page.tsx, Link를 이용해 TaskFlow 기본 App Router 구조를 만듭니다.

공식 문서

이 글이 도움이 되었나요?

조회 중

읽음 기록

읽음 — / 전체 39개 · 필수 38개

이 글을 쓴 해비

웹사이트를 제작·운영하고, 개인 서비스와 자동화·AI 도구를 만듭니다. 직접 만들며 배운 내용과 문제 해결 과정을 BlogFlow에 기록합니다.

새 글 받아보기

RSS 리더에서 BlogFlow의 새 글을 확인할 수 있습니다.

RSS 피드 구독하기