Next.js 교재 · 2편 · 프로젝트 시작

create-next-app 으로 첫 Next.js 프로젝트 시작하기

명령 한 줄이면 끝. 옵션 7개의 의미를 알고 고르자.

터미널에서 create-next-app 으로 새 프로젝트가 생성되는 컨셉 아이소메트릭 일러스트

1편에서 큰 그림을 잡았으니 이제 실제로 만들어 본다. Next.js 공식 권장 방법은 단 하나 — create-next-app. 라이브러리·설정·기본 페이지를 한 번에 깔아 주는 공식 부트스트랩 도구. 옛날 식의 "직접 webpack 설정" 같은 건 잊어도 된다.

이번 편은 명령 한 줄을 곱씹는다. 옵션이 7개 정도 있는데, 첫 입문자가 아무거나 누르면 나중에 후회한다. 한 번 정해두면 시리즈 내내 같은 환경으로 가니까 여기서 똑바로 보고 가자.

1. 사전 준비 — Node.js 18.18 이상

Next.js 14/15 는 Node.js 18.18 이상이 필요하다. 권장은 LTS 인 20.x 또는 22.x. 터미널에서 확인:

$ node --version
v22.10.0
$ npm --version
10.9.0

버전이 낮으면 설치부터. 맥·리눅스는 nvm, 윈도우는 nvm-windows 가 표준. Node.js 시리즈 2편에서 다루는 내용이라 여기선 자세히 안 다룬다.

패키지 매니저 — npm·yarn·pnpm·bun 중 무엇을 써도 된다. 이 교재는 npm(Node 와 같이 깔림)로 통일한다. 회사 들어가서 pnpm 이나 yarn 을 만나도 명령어 두 번째 단어만 바뀐다 (npm install ↔ pnpm install).

2. 명령 한 줄 — 옵션 7개의 의미

준비 됐다면 빈 폴더에서 실행:

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

npx 는 npm 에 같이 깔려있는 도구로, "패키지를 설치하지 않고 한 번만 실행" 시킨다. @latest 는 항상 최신 버전을 받기 위함.

실행하면 7가지 질문이 차례로 뜬다. 첫 입문자 기준 권장 답을 정리.

질문	권장	이유
TypeScript?	Yes	2026 표준. 입문이라도 처음부터 익히는 게 낫다.
ESLint?	Yes	코드 검사. 끄면 나중에 켤 때 빨간 줄 폭발.
Tailwind CSS?	Yes	사실상 표준. 안 쓸 거면 No 도 OK.
src/ 디렉토리?	No	교재는 공식 기본인 루트 app/ 으로 간다.
App Router?	Yes	이게 핵심. No 누르면 옛 Pages Router.
Turbopack?	Yes	15 부터 안정. dev 서버가 빠르다.
import alias?	기본값 @/*	엔터로 넘어가면 된다.

잘못 골랐다? 괜찮다. my-app 폴더를 지우고 다시 실행. 첫 1주는 다섯 번쯤 지웠다 만들었다 반복할 수도 있다. 정상.

App Router 질문은 절대 No 하지 말 것 — Pages Router 는 이 교재 23편에서 마이그레이션 시각으로만 잠깐 다룬다. 2026 기준 신규 프로젝트는 App Router 가 표준.

3. 만들어진 폴더 — 무엇이 어디 있나

설치가 끝나면 my-app/ 폴더가 생긴다. 처음 보면 파일이 많아 막막한데, 실제 자주 만지는 건 5~6개뿐.

my-app/
├── app/                    ← 페이지·라우팅 (메인 작업 공간)
│   ├── layout.tsx          공통 레이아웃 (전 페이지 감쌈)
│   ├── page.tsx            루트 "/" 페이지
│   ├── globals.css         전역 CSS
│   └── favicon.ico
├── public/                 ← 정적 파일 (이미지·robots.txt)
├── node_modules/           ← 라이브러리 (건드리지 않음)
├── .next/                  ← 빌드 결과 (건드리지 않음·gitignore 됨)
├── package.json            의존성·스크립트 정의
├── tsconfig.json           TS 설정
├── next.config.mjs         Next.js 설정
├── tailwind.config.ts      Tailwind 설정
└── .eslintrc.json          ESLint 규칙

핵심만 추리면:

app/ — 페이지가 사는 곳. 99% 의 작업이 여기서.
public/ — 빌드 시 그대로 복사되는 정적 파일. 이미지·favicon·robots.txt.
package.json — 의존성 목록과 명령어(dev·build·start) 정의.
next.config.mjs — 빌드 동작 커스터마이즈 (이미지 도메인·redirect·환경변수 등).

나머지(tsconfig·tailwind.config·.eslintrc) 는 처음엔 손대지 않아도 된다. 기본값이 잘 잡혀 있다.

4. dev 서버 — 코드 저장하면 즉시 반영

폴더로 이동해 dev 서버를 띄운다:

$ cd my-app
$ npm run dev

  ▲ Next.js 15.0.0
  - Local:        http://localhost:3000
  - Environments: .env.local

 ✓ Ready in 1.2s

브라우저에서 http://localhost:3000 을 열면 환영 페이지가 뜬다. 이게 app/page.tsx 가 그린 결과.

이제 에디터로 app/page.tsx 를 열어 아무 글자나 바꿔 저장해 보자. 브라우저가 자동으로 새로고침되면서 즉시 반영된다. 이 기능을 HMR(Hot Module Replacement) 이라고 한다 — Next.js 가 코드 변경을 감지해 바뀐 부분만 다시 보낸다.

dev 서버를 꼭 꺼야 하는 경우 — package.json 의존성 추가/제거 후 (npm install X 했을 때). next.config.mjs 수정 후. 환경변수 .env.local 수정 후. 이 3가지는 Ctrl+C 로 끄고 다시 npm run dev.

5. 첫 수정 — Hello 페이지 만들기

app/page.tsx 의 내용을 통째로 교체:

export default function HomePage() {
  return (
    <main style={{ padding: 40, fontFamily: 'sans-serif' }}>
      <h1>안녕, Next.js!</h1>
      <p>첫 프로젝트가 돌아간다. 다음 편에서 폴더 구조를 깊게 본다.</p>
    </main>
  );
}

저장하면 즉시 브라우저에 반영된다. export default 가 페이지 컴포넌트, 함수 이름은 자유. 파일 위치(app/page.tsx) 가 곧 URL(/) 이다.

이 한 줄이 1편에서 말한 "폴더 구조 = 사이트 구조" 의 시작이다. 다음 편에서 폴더를 더 만들면 URL 이 더 생긴다.

요약 — 2편 좌표

여기까지 핵심. Node.js 18.18 이상 → npx create-next-app@latest my-app → 7가지 질문에 권장값(TS·ESLint·Tailwind·App Router·Turbopack 다 Yes, src/ 는 No)으로 답 → cd my-app && npm run dev → localhost:3000 확인 → app/page.tsx 수정해 즉시 반영 경험. 이게 모든 Next.js 프로젝트의 시작이다. 다음 편에서 App Router 의 폴더 구조를 한눈에 정리한다.

다음 편 예고 — App Router 폴더 구조 한눈에

app/ 안의 layout·page·loading·error·not-found 같은 특수 파일이 각각 무엇을 의미하는지.