Next.js 프로젝트 생성
create-next-app 최신 기본값으로 첫 Next.js 프로젝트를 만들고 실행합니다
핵심 요약
npx create-next-app@latest my-first-app --reset-preferences --yes --use-npm으로 추천 기본값 프로젝트를 한 번에 생성합니다.- 추천 기본값에는 TypeScript, ESLint, Tailwind CSS v4, App Router, Turbopack,
AGENTS.md가 포함됩니다. - 프로젝트 경로에는 한글이나 공백을 피하고,
C:\Projects처럼 영문 경로를 사용합니다. - 생성된 폴더에는
src/app/,AGENTS.md,CLAUDE.md,next.config.ts등이 만들어지며,npm run dev후http://localhost:3000에서 확인합니다. - Next.js 16.2에서는 같은 프로젝트의 dev 서버를 두 번 켜면 기존 서버의 PID·포트·URL을 알려주는 lock file 오류가 표시됩니다.
환경 세팅을 마쳤으니 이제 첫 번째 프로젝트를 만들어 보겠습니다. Next.js는 React 기반의 웹 프레임워크로, 바이브코딩으로 웹사이트를 만들 때 출발점으로 삼기 좋습니다.
2026-05-14 기준
npm registry의 next@latest는 Next.js 16.2.6입니다. Next.js 공식 설치 문서는 Node.js 20.9 이상을 요구하며, 새 프로젝트의 추천 기본값에는 TypeScript, ESLint, Tailwind CSS, App Router, Turbopack, AGENTS.md가 포함됩니다.
프로젝트 폴더 위치 결정
먼저 프로젝트를 저장할 폴더를 정합니다. PowerShell에서 아래 명령어를 실행합니다:
mkdir C:\Projects
cd C:\Projects폴더 위치는 자유롭게
C:\Projects는 예시입니다. 바탕화면이나 문서 폴더 등 원하는 곳에 만들어도 됩니다. 단, 경로에 한글이나 공백이 없는 것이 좋습니다.
create-next-app 실행
아래 명령어로 Next.js 프로젝트를 생성합니다. --reset-preferences는 예전에 저장된 선택값을 지우고, --yes는 최신 추천 기본값으로 바로 생성합니다:
npx create-next-app@latest my-first-app --reset-preferences --yes --use-npm명령어 설명
npx: npm에 포함된 도구. 패키지를 다운로드하고 바로 실행합니다create-next-app@latest: Next.js 프로젝트 생성 도구의 최신 버전my-first-app: 프로젝트 이름 (원하는 이름으로 바꿔도 됩니다)--reset-preferences: 이전에 저장된 CLI 선택값을 초기화합니다--yes: 추천 기본값을 자동 선택합니다--use-npm: npm으로 의존성을 설치합니다
옵션 선택
위 명령어처럼 --yes를 쓰면 옵션 질문 없이 바로 생성됩니다.
직접 선택하고 싶다면 아래처럼 실행합니다:
npx create-next-app@latest my-first-app --reset-preferences명령어를 실행하면 프로젝트 이름을 물어본 뒤 설정 방법을 선택하는 화면이 나옵니다:
Would you like to use the recommended Next.js defaults?
> Yes, use recommended defaults
No, reuse previous settings
No, customize settings처음이라면 'Yes, use recommended defaults' 선택
추천 기본값(TypeScript + ESLint + Tailwind CSS + App Router + Turbopack + AGENTS.md)이 바이브코딩에 최적의 조합입니다. 그대로 선택하세요.
커스텀 설정을 선택하면 아래 질문들이 나옵니다:
| 질문 | 추천 선택 | 설명 |
|---|---|---|
| Would you like to use TypeScript? | Yes | 타입 안전성 제공, Claude Code와 잘 맞음 |
| Which linter would you like to use? | ESLint | 코드 품질 검사 도구 (Biome도 선택 가능) |
| Would you like to use Tailwind CSS? | Yes | CSS 스타일링 프레임워크 (v4) |
| Would you like to use React Compiler? | No | 아직 실험적 기능이므로 초보자는 No |
Would you like your code inside a src/ directory? | Yes | 코드 구조 정리에 도움 |
| Would you like to use App Router? | Yes | Next.js 최신 라우팅 방식 |
| Would you like to customize the import alias? | No | 기본값(@/*) 사용 |
| Would you like to include AGENTS.md? | Yes | AI 에이전트가 설치된 Next.js 버전의 문서를 읽게 함 |
프로젝트 구조
생성이 완료되면 my-first-app 폴더 안에 아래와 같은 파일들이 만들어집니다:
my-first-app/
├── src/
│ └── app/ ← 페이지 코드가 들어가는 곳
│ ├── layout.tsx ← 전체 레이아웃
│ ├── page.tsx ← 메인 페이지
│ └── globals.css ← 전체 스타일
├── public/ ← 이미지 등 정적 파일
├── AGENTS.md ← AI 에이전트용 Next.js 문서 안내
├── CLAUDE.md ← Claude Code가 읽는 프로젝트 안내
├── package.json ← 프로젝트 설정
├── next.config.ts ← Next.js 설정
└── tsconfig.json ← TypeScript 설정AGENTS.md가 왜 중요한가요?
Next.js 16.2부터 next 패키지 안에 현재 설치된 버전과 맞는 공식 문서가 node_modules/next/dist/docs/로 함께 들어갑니다.
AGENTS.md는 Claude Code 같은 AI 코딩 도구가 이 로컬 문서를 먼저 읽도록 알려줍니다.
Tailwind CSS v4 변경사항
Next.js 16에서는 Tailwind CSS v4가 기본 적용됩니다. 기존의 tailwind.config.ts 파일 대신 CSS 파일 내에서 @theme 지시어로 설정합니다.
지금은 몰라도 됩니다. Claude Code에게 물어보면 설명해줍니다.
지금은 모든 파일을 이해할 필요가 없습니다. Claude Code에게 물어보면 설명해줍니다.
개발 서버 실행
프로젝트 폴더로 이동하고 개발 서버를 실행합니다:
cd my-first-app
npm run dev아래와 같은 메시지가 나타나면 성공입니다:
▲ Next.js 16.2.x (Turbopack)
- Local: http://localhost:3000Next.js 16.2에서는 개발 서버가 이미 돌고 있을 때 두 번째 next dev를 시작하면 기존 서버의 PID, 포트, URL을 알려주는 lock file 오류가 뜹니다. 같은 프로젝트에서 서버를 여러 번 켜려 한다면 안내된 URL로 접속하거나 기존 프로세스를 종료하면 됩니다.
브라우저에서 확인
웹 브라우저를 열고 주소창에 아래 주소를 입력합니다:
http://localhost:3000Next.js 기본 페이지가 보이면 프로젝트가 제대로 동작하고 있는 것입니다.
개발 서버 종료 방법
터미널에서 Ctrl + C를 누르면 개발 서버가 종료됩니다. 서버가 종료되면 브라우저에서 페이지가 더 이상 표시되지 않습니다.