Next.js 16 + Turbopack + pnpm 모노레포: Docker 빌드 완전 정복

들어가며

Next.js 16이 출시되면서 Turbopack이 기본 번들러로 자리 잡았습니다. 하지만 pnpm 모노레포 환경에서 Docker 이미지를 빌드하려다 보면 예상치 못한 복병들을 만나게 됩니다.

 

이 글은 제가 실제로 겪었던 문제들과 해결 과정을 상세히 기록한 것입니다. 단순한 튜토리얼이 아닌, 왜 이런 문제가 발생했고, 어떻게 해결했는지에 초점을 맞춰 작성했습니다.

---

🎯 목표

pnpm workspace 모노레포 구조에서 Next.js 16 프론트엔드를 Docker로 배포할 수 있는 Dockerfile 작성

프로젝트 구조:

web10-beastcamp/
├── pnpm-workspace.yaml
├── package.json
├── frontend/
│   ├── package.json
│   └── next.config.ts
├── backend/
│   ├── api-server/
│   └── ticket-server/
└── packages/
    └── shared-types/

---

1단계: 첫 시도 - Nginx 기반 접근

처음에는 Next.js를 정적 사이트로 빌드해서 Nginx로 서빙하는 전통적인 방식을 시도했습니다.

# ❌ 초기 버전 (작동하지 않음)
FROM node:22-alpine AS builder
WORKDIR /app
COPY . .
RUN npm install -g pnpm
RUN pnpm install
RUN pnpm build

FROM nginx:alpine
COPY --from=builder /app/frontend/dist /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

🚨 첫 번째 벽: 파일을 찾을 수 없다

$ docker build -f frontend/Dockerfile -t frontend .
[+] Building 2.3s (8/10)
 => ERROR [deps 4/7] COPY pnpm-workspace.yaml package.json pnpm-lock.yaml ./
------
 > [deps 4/7] COPY pnpm-workspace.yaml package.json pnpm-lock.yaml ./
------
failed to compute cache key: "/pnpm-workspace.yaml" not found

 

원인: Dockerfile이 frontend/ 디렉토리에 있지만, 빌드에 필요한 파일들이 상위 디렉토리(루트)에 있어서 접근할 수 없었습니다.

해결: Docker build context를 프로젝트 루트로 설정하고, Dockerfile 경로를 -f 플래그로 지정합니다.

# ✅ 올바른 빌드 명령
docker build -f frontend/Dockerfile -t frontend .
#                                            ^ 루트에서 실행

---

2단계: pnpm workspace 의존성 설치

모노레포에서는 workspace 간 의존성이 있기 때문에, 단순히 pnpm install만으로는 부족합니다.

# Stage 1: Dependencies
FROM node:22-alpine AS deps
RUN corepack enable && corepack prepare pnpm@latest --activate
WORKDIR /app

# 루트 workspace 파일들을 먼저 복사
COPY pnpm-workspace.yaml package.json pnpm-lock.yaml ./
COPY packages ./packages
COPY frontend/package.json ./frontend/

# --filter 플래그로 frontend와 그 의존성만 설치
RUN pnpm install --frozen-lockfile --filter frontend...

💡 핵심 포인트

• --filter frontend... : frontend 패키지와 그것이 의존하는 모든 workspace 패키지를 설치합니다
• --frozen-lockfile : lock 파일 변경을 방지하여 일관된 빌드를 보장합니다
• packages 디렉토리를 먼저 복사해야 workspace 의존성 해석이 가능합니다

---

3단계: Next.js 16 + Turbopack의 충격

빌드가 시작되는가 싶더니, 새로운 에러가 등장했습니다.

$ pnpm build
Error: Next.js inferred your workspace root at /app, but it may not be correct.
We couldn't find the Next.js package (next/package.json).

Please configure `turbopack.root` in your next.config.js to point to your project root.

🔍 문제 분석

Next.js 16부터 Turbopack이 기본 번들러가 되면서, workspace root를 자동으로 추론하려고 시도합니다. 하지만 pnpm의 특수한 디렉토리 구조(심볼릭 링크 기반)와 충돌하면서 next/package.json을 찾지 못합니다.

 

pnpm의 node_modules 구조:

node_modules/
├── .pnpm/                    # 실제 패키지들이 저장되는 store
│   ├── next@16.1.1/
│   └── react@19.2.3/
└── next -> .pnpm/next@16.1.1/node_modules/next  # 심볼릭 링크

 

Turbopack은 이 심볼릭 링크를 제대로 따라가지 못하고 있었습니다.

✅ 해결 방법: turbopack.root 설정

next.config.ts에 명시적으로 workspace root를 지정합니다.

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  turbopack: {
    root: "..",  // 상위 디렉토리를 workspace root로 지정
  },
  reactCompiler: true,
  output: "standalone",
};

export default nextConfig;

 

이제 Turbopack이 올바른 위치에서 패키지를 찾을 수 있습니다.

---

4단계: Standalone 모드와 최적화

Nginx 대신 Next.js의 standalone 모드를 사용하기로 결정했습니다.

왜 Standalone인가?

1. Server-Side Rendering(SSR) 지원: Nginx는 정적 파일만 서빙할 수 있지만, standalone은 SSR과 API Routes를 지원합니다
2. 최소 번들 크기: 필요한 의존성만 포함된 경량 빌드를 생성합니다
3. self-contained: Node.js만 있으면 실행 가능한 독립적인 서버입니다

// next.config.ts
const nextConfig: NextConfig = {
  output: "standalone",  // 이 한 줄이 마법을 일으킵니다
};

Standalone 빌드가 생성하는 것

frontend/.next/
├── standalone/          # 실행 가능한 서버
│   ├── server.js       # 진입점
│   ├── package.json
│   └── node_modules/   # 필요한 의존성만 (심볼릭 링크)
└── static/             # 정적 자산들

---

5단계: 최종 Dockerfile - Multi-stage Build

이제 모든 퍼즐 조각을 맞춰봅시다.

# Stage 1: Dependencies
FROM node:22-alpine AS deps
RUN corepack enable && corepack prepare pnpm@latest --activate
WORKDIR /app

# Copy root workspace files
COPY pnpm-workspace.yaml package.json pnpm-lock.yaml ./
COPY packages ./packages

# Copy frontend package.json
COPY frontend/package.json ./frontend/

# Install dependencies
RUN pnpm install --frozen-lockfile --filter frontend...

# Stage 2: Builder
FROM node:22-alpine AS builder
RUN corepack enable && corepack prepare pnpm@latest --activate
WORKDIR /app

# Build arguments for Next.js environment variables
ARG NEXT_PUBLIC_API_URL
ARG NEXT_PUBLIC_API_MODE

# Copy dependencies from deps stage
COPY --from=deps /app/node_modules ./node_modules
COPY --from=deps /app/frontend/node_modules ./frontend/node_modules
COPY --from=deps /app/packages ./packages

# Copy source files
COPY frontend ./frontend
COPY pnpm-workspace.yaml package.json ./

# Build application
WORKDIR /app/frontend
RUN pnpm build

# Stage 3: Production with Node.js (for standalone Next.js)
FROM node:22-alpine AS runner
WORKDIR /app

ENV NODE_ENV=production
ENV NEXT_TELEMETRY_DISABLED=1

RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

# standalone은 필요한 모든 의존성을 이미 포함하고 있음
# 전체 standalone 구조를 복사
COPY --from=builder --chown=nextjs:nodejs /app/frontend/.next/standalone ./

# static 파일들을 올바른 중첩 경로에 복사
COPY --from=builder --chown=nextjs:nodejs /app/frontend/.next/static ./frontend/.next/static
COPY --from=builder --chown=nextjs:nodejs /app/frontend/public ./frontend/public

USER nextjs

EXPOSE 3000

ENV PORT=3000
ENV HOSTNAME="0.0.0.0"

# frontend 디렉토리로 이동해서 server.js 실행
WORKDIR /app/frontend
CMD ["node", "server.js"]

🎨 아키텍처 설명

Stage 1 (deps): 의존성만 설치

• 빌드 캐싱 최적화: package.json이 변경되지 않으면 이 레이어를 재사용
• --filter frontend...로 필요한 패키지만 설치

Stage 2 (builder): 애플리케이션 빌드

• 소스 코드 변경이 의존성 설치에 영향을 주지 않음
• ARG로 빌드 타임 환경변수 주입 가능

Stage 3 (runner): 프로덕션 실행

• 빌드 산출물만 복사하여 이미지 크기 최소화
• non-root 사용자(nextjs)로 실행하여 보안 강화
• standalone 출력물의 디렉토리 구조를 그대로 유지

---

6단계: 빌드 최적화 - .dockerignore

불필요한 파일들을 제외하여 빌드 속도를 높입니다.

# .dockerignore
node_modules
.next
.git
.gitignore
README.md
.env*.local
.DS_Store
*.md

---

실행 및 검증

빌드

docker build -f frontend/Dockerfile -t beastcamp-frontend .

실행

docker run -d \
  --name frontend \
  -p 3000:3000 \
  -e NEXT_PUBLIC_API_URL=https://api.example.com \
  beastcamp-frontend

검증

$ docker logs -f frontend
   ▲ Next.js 16.1.1
   - Local:        http://localhost:3000
   - Network:      http://0.0.0.0:3000

 ✓ Starting...
 ✓ Ready in 89ms

$ curl -I http://localhost:3000
HTTP/1.1 200 OK
x-powered-by: Next.js

 

---

주요 교훈 (Key Takeaways)

1. Turbopack과 pnpm의 궁합 문제

• Next.js 16의 Turbopack은 pnpm의 심볼릭 링크 구조를 완벽히 지원하지 못합니다
• turbopack.root 설정으로 workspace root를 명시하면 해결됩니다

2. Standalone 모드의 장점

• SSR/ISR을 지원하는 완전한 서버
• 최소한의 의존성만 포함되어 이미지 크기 최소화
• Nginx 설정 없이 바로 프로덕션 배포 가능

3. Multi-stage Build의 중요성

• 의존성 설치와 빌드를 분리하여 캐싱 효율 극대화
• 최종 이미지에는 실행에 필요한 파일만 포함

4. pnpm Workspace 필터링

• --filter frontend...는 세 개의 점(...)이 핵심
• 해당 패키지와 그것이 의존하는 모든 workspace 패키지를 포함

5. 보안 고려사항

• non-root 사용자로 컨테이너 실행
• 민감한 정보는 빌드 아규먼트나 환경변수로 주입
• .dockerignore로 불필요한 파일 노출 방지

---

성능 메트릭

항목	수치
최종 이미지 크기	~180MB (alpine 기반)
빌드 시간 (캐시 없음)	~3분
빌드 시간 (캐시 있음)	~15초
시작 시간	~90ms
메모리 사용량	~150MB (유휴 상태)

---

트러블슈팅 가이드

Q: "Cannot find module 'next'" 에러가 발생합니다

원인: standalone 빌드의 심볼릭 링크가 제대로 복사되지 않았습니다.

해결:

# standalone 전체 구조를 복사
COPY --from=builder /app/frontend/.next/standalone ./

Q: 빌드는 되는데 실행 시 404가 납니다

원인: static 파일들이 올바른 경로에 복사되지 않았습니다.

해결:

# 중첩된 경로 구조를 그대로 유지
COPY --from=builder /app/frontend/.next/static ./frontend/.next/static
COPY --from=builder /app/frontend/public ./frontend/public

Q: 환경변수가 빌드 타임에 적용되지 않습니다

원인: NEXT_PUBLIC_* 변수는 빌드 시점에 번들에 포함됩니다.

해결:

ARG NEXT_PUBLIC_API_URL
# 빌드 시 전달: docker build --build-arg NEXT_PUBLIC_API_URL=...

---

마치며

Next.js 16의 Turbopack과 pnpm 모노레포를 Docker로 빌드하는 과정은 생각보다 복잡했지만, 각 문제의 원인을 이해하고 나니 해결책이 명확해졌습니다.

핵심은 Turbopack의 workspace root 설정과 standalone 모드의 디렉토리 구조 유지였습니다.

이 글이 비슷한 문제를 겪고 있는 분들에게 도움이 되길 바랍니다. 질문이나 개선 사항이 있다면 언제든지 피드백 주세요!

---

참고 자료

• Next.js Standalone Output
• pnpm Workspace Filtering
• Turbopack Configuration
• Docker Multi-stage Builds