4단계 — Node.js + pnpm + 첫 React

JavaScript 를 브라우저 밖에서 실행하는 게 Node.js, 외부 코드를 끌어다 쓰는 도구가 패키지 매니저. 이 두 개가 있어야 React · Next.js 가 돕니다.

1. Node.js 설치

# Windows
winget install OpenJS.NodeJS.LTS

# macOS
brew install node

# Linux (권장: NodeSource)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install nodejs

버전 확인:

node --version   # v20.x 이상
npm --version

LTS (Long-term support) 버전을 쓰는 게 안정적. 2026 기준 Node 20 · 22 가 LTS.

2. 버전 관리 — nvm 또는 fnm

프로젝트마다 Node 버전이 다를 때 필요.

# macOS / Linux — nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

nvm install 20
nvm use 20
nvm alias default 20

Windows 는 fnm 또는 nvs 권장 (nvm-windows 는 별도 프로젝트).

3. 패키지 매니저 3 종

이름	장점	단점
npm	Node 내장 · 가장 범용	느림 · node_modules 거대
yarn	빠름 · monorepo 지원	버전 1 과 2+ 동작 차이
pnpm	가장 빠름 · 디스크 절약 · strict	학습 곡선 조금

warragon 은 pnpm 채택. 다른 선택도 괜찮지만 한 프로젝트 내에서는 혼용 금지.

4. pnpm 활성화 — corepack

Node 16.13+ 에는 corepack 이 내장. pnpm 을 별도 설치하지 않고 활성화만.

corepack enable
corepack prepare pnpm@10.33.0 --activate

pnpm --version

프로젝트 package.json 에 "packageManager": "pnpm@10.33.0" 가 있으면 corepack 이 자동으로 그 버전을 씁니다.

5. pnpm 핵심 명령

pnpm install                 # package.json 의 의존성 설치
pnpm add react               # 새 패키지 추가
pnpm add -D typescript       # dev dependency
pnpm remove lodash           # 제거
pnpm update                  # 업데이트
pnpm run dev                 # 스크립트 실행 (pnpm dev 도 가능)
pnpm dlx create-next-app     # 임시 실행 (npx 대응)

pnpm i = pnpm install 단축.

6. package.json 읽기

{
  "name": "my-app",
  "version": "0.1.0",
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  },
  "dependencies": {
    "next": "16.0.0",
    "react": "19.0.0"
  },
  "devDependencies": {
    "typescript": "5.6.0"
  },
  "packageManager": "pnpm@10.33.0"
}

• dependencies — 런타임 필요
• devDependencies — 빌드 · 테스트에만
• scripts — pnpm <이름> 으로 실행

7. node_modules 와 lockfile

• node_modules/ — 실제 다운로드된 패키지. .gitignore 필수 · 매우 큼
• pnpm-lock.yaml — 정확히 어떤 버전을 설치했는지 고정. 반드시 커밋

팀원 모두 같은 버전을 쓰도록 lockfile 이 기준. 삭제 후 pnpm install 하면 같은 결과.

8. 첫 Next.js 프로젝트

pnpm create next-app@latest my-first-app
# 질문에 아래처럼 응답:
# TypeScript? Yes
# ESLint? Yes
# Tailwind CSS? Yes
# src/ directory? Yes
# App Router? Yes
# Turbopack? Yes
# import alias? No (기본 @/*)

cd my-first-app
pnpm dev

브라우저에서 http://localhost:3000 열면 첫 페이지.

9. 폴더 구조 살펴보기

my-first-app/
├── src/
│   └── app/
│       ├── layout.tsx       # 전역 레이아웃
│       ├── page.tsx         # 홈페이지 (/)
│       └── globals.css      # 전역 스타일
├── public/                  # 정적 파일 (이미지 등)
├── package.json
├── pnpm-lock.yaml           # 커밋 필수
├── next.config.ts
├── tsconfig.json
└── .gitignore

src/app/page.tsx 를 수정하면 화면이 자동 새로고침 (HMR).

10. 자주 걸리는 자리

• 다른 패키지 매니저 섞어서 — package-lock.json + pnpm-lock.yaml 둘 다 생기면 혼란. 하나만 유지
• port 3000 이미 사용 중 — pnpm dev -- -p 3001 로 변경
• cannot find module — pnpm install 다시 또는 node_modules 삭제 후 재설치
• Node 버전 불일치 — .nvmrc 파일 (echo "20" > .nvmrc) 로 고정

11. package.json engines

{
  "engines": {
    "node": ">=20",
    "pnpm": ">=10"
  }
}

요구 버전 명시. 설치 시 경고 · 위반 시 실패하도록 설정 가능.

하고픈 말

Node 20 + pnpm + Next 16 조합이 2026 기준 가장 표준적. 한 번 세팅하면 이후 프로젝트마다 같은 사이클로 빠르게 시작 가능합니다.

Next

• 05-ai-tools

Node.js 공식 · pnpm 공식 · Next.js App Router 를 참고합니다.