🚀 Next.js 프로젝트 설정 실전 — package.json 완성형 아키텍처

📋 목차

• 📌 이 문서를 읽기 전에
• 🤔 왜 알아야 하는가
• 🏗️ 완성형 package.json 전체
• 🧪 의존성 분류 근거
• ⚡ Turbopack & 개발 서버 최적화
• 📁 팀 환경 통일 파일들
• 🐳 Docker 최적화
• 🗂️ 모노레포 workspace 기초
• 🏁 이번에 배운 내용 총정리
• 📝 마무리 퀴즈
• 🐣 영철이의 퇴근 일기
• 🔗 더 알아보기

📌 이 문서를 읽기 전에

⏱️ 예상 읽기 시간: 20분(전체) / 핵심 파트만: 10분 (완성형 package.json + Docker)

🗺️ 이 문서의 흐름
완성형 package.json → 의존성 분류 근거 → Turbopack 설정 → 팀 환경 통일 → Docker 최적화 → 모노레포 기초

🎯 이 문서를 다 읽으면 할 수 있는 것

• Next.js 14 App Router 프로젝트의 package.json 을 처음부터 설계할 수 있다
• 모든 패키지의 dependencies/devDependencies 배치 근거를 즉시 설명할 수 있다
• .nvmrc 와 .npmrc 로 팀 전체의 Node.js, npm 버전을 통일할 수 있다
• Docker 멀티 스테이지 빌드에서 devDependencies 를 제외해 이미지 크기를 최소화할 수 있다
• npm workspaces 로 간단한 모노레포 구조를 설계할 수 있다

🗺️ 이 문서의 배경 세계관: '영수네 커뮤니티'

• 🐣 영철 ( 신입 ): "리드 님, 저 next create-app 으로 만든 기본 구조에서 패키지들을 막 추가했는데, 어느 게 어디 들어가야 하는지 자신이 없어요. 특히 @prisma/client 랑 prisma 분리, tailwindcss devDependencies 는 배웠는데... Docker 에서도 devDependencies 를 제외해야 한다는 건 어떻게 하는 건가요? 그리고 팀이 커지면 모노레포로 가야 한다는데, workspace 는 어떻게 시작하나요?"
• 🦁 영호 ( 리드 ): "오늘 영수네 커뮤니티 전체 package.json 을 처음부터 설계해볼게요. 모든 패키지를 어디에 놓는지, 왜 거기 넣는지 근거까지 같이 설명할게요. Docker 최적화랑 workspace 도요."

🤔 왜 알아야 하는가

팀이 커지고 프로젝트가 성숙해질수록, "일단 돌아가면 됐지" 식의 package.json 은 기술 부채가 된다. devDependencies 에 들어가야 할 게 dependencies 에 있으면 Docker 이미지가 불필요하게 커지고, engines 가 없으면 팀원마다 다른 Node 버전을 쓰다 묘한 버그가 생긴다.

이 가이드에서는 영수네 커뮤니티의 package.json 을 처음부터 설계하는 과정을 보여준다. 단순히 템플릿을 복사하는 것이 아니라, 왜 이 구조인지 근거를 함께 이해하는 것이 목표다.

🏗️ 완성형 package.json 전체

{
  "name": "youngsoo-community",
  "version": "1.0.0",
  "private": true, // 🦁 실수로 npm registry에 배포되는 걸 막아주는 가장 중요한 안전장치예요!
  "description": "개발자 스터디 매칭 커뮤니티 서비스",
  "engines": {
    // 💡 팀원 모두가 "최소한 이 버전 이상의 Node.js"를 써야 버그가 안 생깁니다.
    "node": ">=18.17.0",
    "npm": ">=9.0.0"
  },
 
  "scripts": {
    "dev":           "next dev",
    "dev:turbo":     "next dev --turbo", // 🦁 Rust로 만든 초고속 엔진! 개발 속도가 훨씬 빨라져요.
    "build":         "next build",
    "validate":      "run-s type-check lint test", // 💡 배포 전 '3종 세트'를 한 번에 검사합니다.
    "prebuild":      "npm run type-check", // 빌드 버튼 누르자마자 타입 에러부터 체크!
    "prepare":       "husky", // 🐯 npm install만 해도 git 훅이 자동 세팅되게 합니다.
    "postinstall":   "prisma generate" // 의존성 깔고 나서 DB 클라이언트도 자동 생성!
  },
 
  "dependencies": {
    "next": "^14.1.0",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
 
    "@prisma/client": "^5.9.1",
    "next-auth": "^4.24.5",
 
    "jotai": "^2.6.4",
    "@tanstack/react-query": "^5.18.0",
    "@tanstack/react-query-devtools": "^5.18.0",
 
    "zod": "^3.22.4",
    "socket.io-client": "^4.7.2",
    "date-fns": "^3.3.0"
  },
 
  "devDependencies": {
    "typescript": "^5.3.3",
    "@types/react": "^18.2.48",
    "@types/react-dom": "^18.2.18",
    "@types/node": "^20.11.5",
 
    "eslint": "^8.56.0",
    "eslint-config-next": "^14.1.0",
    "prettier": "^3.2.4",
 
    "tailwindcss": "^3.4.1",
    "autoprefixer": "^10.4.17",
    "postcss": "^8.4.33",
 
    "prisma": "^5.9.1",
 
    "jest": "^29.7.0",
    "jest-environment-jsdom": "^29.7.0",
    "@testing-library/react": "^14.1.2",
    "@testing-library/jest-dom": "^6.4.1",
 
    "husky": "^9.0.10",
    "lint-staged": "^15.2.2",
    "npm-run-all": "^4.1.5",
    "@next/bundle-analyzer": "^14.1.0",
    "cross-env": "^7.0.3"
  },
 
  "lint-staged": {
    "*.{ts,tsx,js,jsx}": ["eslint --fix", "prettier --write"],
    "*.{json,md,css}": "prettier --write"
  }
}

🧪 의존성 분류 근거 — 모든 패키지를 왜 거기에 놓았나

dependencies 분류 근거

판단 기준: "프로덕션 서버가 실행 중에 이 패키지의 코드가 실행되는가?"

devDependencies 분류 근거

⚡ Turbopack & 개발 서버 최적화

Turbopack 이란

Vercel 이 개발한 Rust 기반 번들러. 기존 Webpack 대비:

• 초기 컴파일 최대 76% 빠름
• 코드 변경 시 HMR 최대 96% 빠름

{
  "scripts": {
    "dev":       "next dev",
    "dev:turbo": "next dev --turbo"
  }
}

Turbopack 사용 전 확인 사항:

// next.config.js 에 커스텀 webpack 설정이 있다면
const nextConfig = {
  webpack: (config) => {
    // ← 이런 커스텀 설정이 Turbopack 과 호환되는지 먼저 확인
    return config
  }
}

현재 Next.js 14.1+ 에서 Turbopack 은 개발 서버(next dev) 에서 안정화됨. next build 에서의 Turbopack 은 아직 실험적.

📁 팀 환경 통일 파일들 — .nvmrc, .npmrc

.nvmrc — Node.js 버전 통일

# .nvmrc (프로젝트 루트)
# 🦁 "우리 팀은 Node.js 18.17.0 버전을 기준으로 개발합니다" 라고 말해주는 파일이에요.
18.17.0

# 팀원이 프로젝트 진입 시
nvm use          # .nvmrc 의 버전으로 자동 전환
# Found '/path/to/project/.nvmrc' with version <18.17.0>
# Now using node v18.17.0

nvm 자동 전환 설정 (선택): ~/.zshrc 에 다음을 추가하면 디렉터리 진입 시 자동으로 Node 버전이 바뀐다:

# ~/.zshrc
autoload -U add-zsh-hook
load-nvmrc() {
  local nvmrc_path="$(nvm_find_nvmrc)"
  if [ -n "$nvmrc_path" ]; then
    nvm use
  fi
}
add-zsh-hook chpwd load-nvmrc
load-nvmrc

.npmrc — npm 동작 제어

# .npmrc
engine-strict=true       # engines 버전 불일치 시 install 에러
 
# 내부 레지스트리 설정 (회사 내부 패키지 사용 시)
@youngsoo:registry=https://npm.youngsoo.internal.com/
 
# CI 환경에서 audit 경고 무시 (CI 에서는 별도 audit 단계가 있음)
# fund=false              # 후원 메시지 숨기기

파일 구조 총정리

youngsoo-community/
  .nvmrc                 ← Node.js 버전 18.17.0
  .npmrc                 ← engine-strict=true, 레지스트리 설정
  package.json           ← engines 필드 포함
  package-lock.json      ← 정확한 버전 잠금 (git 커밋 필수)
  .gitignore             ← node_modules/, .next/

🐳 Docker 최적화 — 프로덕션 이미지 최소화

멀티 스테이지 빌드로 devDependencies 제거

# ─── Stage 1: 의존성 설치 + 빌드 (요리 준비) ───
FROM node:18-alpine AS builder
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci # 🦁 CI 환경에선 lock파일 기준으로 엄격하게 설치!
COPY . .
RUN npm run build # 💡 여기서 .next 폴더가 만들어집니다.
 
# ─── Stage 2: 프로덕션 실행 (진짜 서빙) ───
FROM node:18-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
# 🐯 standalone 모드: 빌드 결과물 중 '실행에 꼭 필요한 파일'만 쏙 골라냅니다.
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public
CMD ["node", "server.js"]

🔥 왜 Stage 가 두 개인가:

• Stage 1 (builder): devDependencies 포함 전체 설치 → Next.js 빌드
• Stage 2 (runner): 빌드 결과물(.next/)만 복사 → devDependencies 없음

최종 Docker 이미지에는 devDependencies 가 포함되지 않아 이미지 크기가 크게 줄어든다.

next.config.js 에 output: 'standalone' 필수:

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'standalone'
}
 
module.exports = nextConfig

이 설정 없이는 server.js 가 생성되지 않는다.

🗂️ 모노레포 workspace 기초

팀이 커지면 apps/community (Next.js 앱)와 packages/ui (공유 컴포넌트 라이브러리)를 하나의 레포에서 관리하는 모노레포 구조가 필요하다.

workspace 설정

youngsoo-monorepo/
  package.json           ← 루트 package.json (workspace 설정)
  apps/
    community/           ← Next.js 앱
      package.json
    admin/               ← 관리자 앱
      package.json
  packages/
    ui/                  ← @youngsoo/ui 라이브러리
      package.json
    utils/               ← @youngsoo/utils 공유 유틸
      package.json

// 루트 package.json
{
  "name": "youngsoo-monorepo",
  "private": true,
  "workspaces": [
    "apps/*",
    "packages/*"
  ]
}

workspace 내 패키지 참조

// apps/community/package.json
{
  "name": "youngsoo-community",
  "dependencies": {
    // 🦁 멀리 있는 npm 서버가 아니라, 우리 폴더 안에 있는 라이브러리를 보겠다는 뜻이에요!
    "@youngsoo/ui": "workspace:*",
    "@youngsoo/utils": "workspace:*"
  }
}

workspace:* 는 npm registry 가 아닌 로컬 packages/ui 폴더에서 직접 가져온다.

workspace 명령어

# 루트에서 전체 의존성 설치
npm install    # 모든 workspace 의 의존성을 한 번에 설치
 
# 특정 workspace 에서 명령 실행
npm run build --workspace=apps/community
npm run build --workspace=packages/ui
 
# 모든 workspace 에서 동시에 실행
npm run build --workspaces
 
# 특정 workspace 에 패키지 설치
npm install react --workspace=apps/community

🏁 이번에 배운 내용 총정리

📝 마무리 퀴즈

Q1. Next.js 프로젝트에서 tailwindcss 를 devDependencies 에 넣어야 하는 이유로 가장 적절한 것은?

a) Tailwind 는 CSS 프레임워크라서 JavaScript 런타임과 무관하다
b) Next.js 빌드 시 Tailwind 가 사용된 클래스를 스캔해 CSS 파일을 생성하므로, 빌드 완료 후 프로덕션 서버에는 CSS 파일만 있으면 되고 tailwindcss 자체는 필요 없다
c) Tailwind 는 CDN 으로만 사용해야 한다
d) devDependencies 와 dependencies 어디에 넣어도 동작이 같다

✅ 정답: b

💡 상세 해설:

• 원리 설명: Next.js 빌드 과정에서 tailwindcss + postcss + autoprefixer 가 .tsx 파일의 Tailwind 클래스를 스캔하고 .next/static/css/xxx.css 를 생성한다. 이 과정이 완료된 후, 프로덕션 서버는 이 CSS 파일만 정적으로 서빙한다. 서버가 실행 중에 tailwindcss 코드가 실행되는 일은 없으므로 devDependencies 가 맞다.
• 실용적 의미: Docker 멀티 스테이지 빌드에서 devDependencies 는 최종 이미지에 포함되지 않는다. tailwindcss 를 dependencies 에 잘못 넣으면 약 5MB 의 불필요한 코드가 Docker 이미지에 포함된다.
• 📌 핵심 기억법: "Tailwind 는 빌드 공장의 도구. 공장에서 물건이 나온 뒤 고객 집에 도구를 보내지는 않는다."

Q2. Docker 멀티 스테이지 빌드에서 Stage 를 분리하는 주요 목적은?

a) 빌드 속도를 높이기 위해 여러 CPU 코어를 사용하려고
b) Stage 1 에서만 사용되는 devDependencies, 빌드 도구 등이 최종 이미지에 포함되지 않도록 하여 이미지 크기를 줄인다
c) Dockerfile 코드를 보기 좋게 정리하려고
d) 여러 기반 이미지를 동시에 사용하기 위해

✅ 정답: b — devDependencies 제외로 이미지 크기 최소화

💡 상세 해설:

• 원리 설명: Stage 1 (builder)에서는 빌드에 필요한 모든 것(devDependencies, 소스코드, 빌드 도구)을 사용해 Next.js 빌드를 실행한다. Stage 2 (runner)에서는 .next/ 결과물만 복사한다. 최종 Docker 이미지에는 Stage 2 의 내용만 포함되므로 devDependencies 가 완전히 제거된다. 결과적으로 이미지 크기가 수백 MB 줄어드는 경우도 많다.
• 📌 핵심 기억법: "멀티 스테이지 = 빌드 환경과 실행 환경 분리. 실행 환경에는 최소한만."

Q3. 🐣 영철이의 테스트 타임 — 시니어 면접 도전

면접관 (영호 스타일)이 물었다. "Next.js 프로젝트를 Docker 로 배포할 때, npm ci 와 npm ci --omit=dev 를 Dockerfile 의 어떤 Stage 에서 각각 사용해야 하는지, 그리고 그 이유를 설명해주세요."

✅ 정답: Stage 1 (builder)에서는 npm ci, Stage 2 (runner)에서는 Node.js standalone 실행 — --omit=dev 는 멀티 스테이지에서 별도로 쓰지 않아도 됨

# Stage 1: 빌드
FROM node:18-alpine AS builder
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci                    # devDependencies 포함. 빌드에 필요
COPY . .
RUN npm run build
 
# Stage 2: 실행
FROM node:18-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
# 빌드 결과물만 복사 — node_modules 전체를 복사하지 않음!
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public
CMD ["node", "server.js"]

💡 상세 해설:

• Stage 1 에서 npm ci (전체): Next.js 빌드 시 tailwindcss, typescript, @types/* 등 devDependencies 가 필요하다. --omit=dev 를 쓰면 빌드가 실패한다.
• Stage 2 에서 --omit=dev 가 필요 없는 이유: output: 'standalone' 옵션으로 빌드하면 .next/standalone/ 폴더에 프로덕션 실행에 필요한 최소 파일(node_modules 포함)이 자동으로 생성된다. 이 폴더만 복사하면 이미 devDependencies 가 제거된 상태다.
• 만약 standalone 을 쓰지 않는다면: 다음처럼 production 의존성만 별도로 설치하는 Stage 를 추가할 수 있다:

  FROM node:18-alpine AS deps
  WORKDIR /app
  COPY package.json package-lock.json ./
  RUN npm ci --omit=dev    # production 의존성만

• 📌 핵심 기억법: "빌드할 때는 전부 필요하고, 실행할 때는 결과물만 필요하다. 멀티 스테이지가 이 두 환경을 분리한다."

🐣 영철이의 퇴근 일기

오늘 드디어 영수네 커뮤니티 프로젝트의 package.json 을 완성했다. 그냥 복붙으로 만든 게 아니라, 각 패키지가 왜 거기 들어가는지 근거를 가지고 설계한 첫 번째 경험이었다.

@prisma/client 는 dependencies, prisma (CLI)는 devDependencies — 이게 왜 나뉘는지 이제 눈 감고도 설명할 수 있다. Docker 멀티 스테이지 빌드도 생각보다 어렵지 않았다. "빌드 환경과 실행 환경을 분리한다" 는 원칙 하나로 전부 설명이 됐다.

💡 오늘의 교훈: "좋은 package.json 은 단순히 패키지 목록이 아니다. 프로젝트가 어떤 환경에서 어떻게 실행될지, 어떤 도구가 어느 단계에서 필요한지에 대한 설계도다."

모노레포 workspace 도 슬쩍 맛봤다. 처음엔 복잡해 보였는데, workspace:* 로 로컬 패키지를 참조한다는 게 핵심이더라. 팀이 커지면 그때 본격적으로 파야겠다.

퇴근 후에 치킨 시켰다. 오늘은 좀 자축해도 될 것 같다. 내일은 마지막으로 npm audit 이랑 보안편 해야지.

🔗 더 알아보기

• Next.js 공식 — Docker 배포 가이드
• Next.js 공식 — Turbopack
• npm 공식 문서 — workspaces
• Vercel 공식 Next.js Docker 예시