⏱️ pnpm 입문: 3분 만에 끝내는 Next.js 실전 기반 세팅

2026년 4월 30일 수정됨

📋 개요

원리는 나중에! 당장 프로젝트를 시작해야 하는 주니어를 위한 pnpm + Next.js 밑바닥 세팅 튜토리얼

00. pnpm 입문: 3분 퀵스타트

📋 목차

  1. 총정리
  2. 마무리 퀴즈
  3. 영철이의 퇴근 일기
  4. 더 알아보기

📌 이 문서를 읽기 전에

⏱️ 예상 읽기 시간: 약 10분(전체) / 실습만 따라하기: 3분

🗺️ 이 문서의 흐름

[pnpm 설치] → [프로젝트 생성] → [.npmrc 필수 세팅] → [실행 완료]

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

  • 에러 없이 pnpm 전역 설치를 완료할 수 있다
  • npx 대신 pnpm dlx 로 초기 세팅을 진행할 수 있다
  • Next.js 프로젝트에 필요한 최소한의 .npmrc 설정을 이해하고 작성할 수 있다

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

급하게 세팅이 필요한 영철이와 3분 컷을 약속하는 영호
  • 🐣 영철 ( 신입 ): "영호 님, 01편부터 읽어보려니까 멘탈 모델이니 글로벌 스토어니 원리가 아직 너무 어렵네요... 당장 오늘 오후에 Next.js 로 새 토이 프로젝트 하나 파야 하는데 터미널에서 당장 뭐부터 쳐야 하나요? npx create-next-app 하면 되는 건가요?"
  • 🦁 영호 ( 리드 ): "잠깐! npx 대신 pnpm dlx 를 써보는 것부터 시작해요. 원리는 나중에 천천히 읽어도 됩니다. 지금 당장 터미널 열고 저랑 딱 5줄만 쳐봅시다. 3분 만에 완벽한 pnpm + Next.js 세팅 끝내볼게요."

🤔 왜 알아야 하는가

새로운 도구를 배울 때 가장 큰 진입 장벽은 "그래서 당장 내 노트북에서 어떻게 켜는데?" 이다.

pnpm 의 동작 원리나 모노레포 설정 같은 고급 기능은 당장 몰라도 개발을 시작할 수 있다. 하지만 "올바른 첫 설치 방법(Corepack)" 과 "에러를 예방하는 최소한의 설정(.npmrc)" 을 모른 채 시작하면, 나중에 알 수 없는 모듈 에러에 시달리게 된다.

이 가이드는 가장 빠르고 안전하게 pnpm 기반의 Next.js 프로젝트를 띄우는 실전 매뉴얼이다.

🚀 Step 1. 전역 설치 (Corepack)

가장 권장되는 pnpm 설치 방법은 Corepack 으로 프로젝트의 packageManager 버전에 맞추는 것이다. npm install -g pnpm 보다 팀원 간 버전 충돌이 적다.

# 1. Corepack 활성화 (Node.js LTS 환경에서 사용 가능, 없으면 별도 설치 필요)
corepack enable
 
# 2. 최신 버전의 pnpm 준비
corepack prepare pnpm@latest --activate
 
# 3. 설치 확인
pnpm --version
# 10.x.x 또는 packageManager에 고정한 버전이 나오면 성공

💡 혹시 권한 에러(EACCES) 가 난다면?
macOS/Linux 에서 sudo corepack enable 로 실행해야 할 수도 있다. 그래도 안 되면 npm install -g pnpm 을 사용해도 무방하다.

📦 Step 2. 프로젝트 생성 (pnpm dlx)

pnpm dlx 는 npm 의 npx 와 동일한 역할을 하지만 훨씬 빠르다.

# Next.js App Router 프로젝트 생성
pnpm dlx create-next-app@latest my-pnpm-app
 
# 🦁 인터랙티브 프롬프트가 나오면 아래와 같이 선택:
# ✔ Would you like to use TypeScript? … Yes
# ✔ Would you like to use ESLint? … Yes
# ✔ Would you like to use Tailwind CSS? … Yes
# ✔ Would you like to use `src/` directory? … Yes
# ✔ Would you like to use App Router? (recommended) … Yes
# 생성된 폴더로 이동
cd my-pnpm-app

⚙️ Step 3. 루트 .npmrc 세팅의 정석

이 3분이 나중에 당신의 3시간을 아껴준다.

프로젝트 루트 폴더(my-pnpm-app)에 .npmrc 파일을 만들고 아래 코드를 그대로 붙여넣자. (이 설정 이유가 궁금하다면 나중에 2편. node_modules 구조 해부 편을 읽어보자.)

# 터미널에서 바로 파일 생성하기
cat << EOF > .npmrc
# TypeScript 와 ESLint, Tailwind 계열 호이스팅 (에러 예방)
public-hoist-pattern[]=*types*
public-hoist-pattern[]=*eslint*
public-hoist-pattern[]=tailwindcss
public-hoist-pattern[]=postcss
public-hoist-pattern[]=autoprefixer
EOF

이 코드는 pnpm 의 엄격한 격리 구조 때문에 ESLint 나 Tailwind 가 모듈을 찾지 못하는 뻔한 에러를 사전에 차단하는 "치트키" 다.

🏃 Step 4. 패키지 설치 및 실행

이제 본격적으로 의존성을 설치하고 서버를 띄워보자.

# 앞서 .npmrc 를 추가했으니, 깔끔하게 재설치 한 번 해준다
# (Next.js 가 기본 생성한 것을 pnpm 설정에 맞게 덮어씀)
pnpm install
 
# 개발 서버 실행
pnpm dev

브라우저에서 http://localhost:3000 을 열어보자. 축하한다! 당신의 첫 번째 pnpm 레이싱카가 출발을 시작했다. 🏎️💨

✨ 보너스: 스토어 체감하기

pnpm 의 진짜 위력(디스크 공유와 극단적인 속도)을 1초 만에 확인해 볼 수 있다.

# 터미널을 열고 용량이 가장 큰 컴포넌트 라이브러리를 하나 추가해보자
pnpm add framer-motion

눈 깜짝할 새에 설치가 끝날 것이다.
이제 이 패키지를 지웠다가 다시 설치해보자.

# 제거
pnpm remove framer-motion
 
# 다시 설치
pnpm add framer-motion

두 번째 설치는 뭔가 다운로드 받는 과정 없이 곧바로 끝난다. 이미 당신의 PC 어딘가(.pnpm-store)에 원본이 저장되어 있고, node_modules 에는 그 원본을 향하는 "바로가기(하드링크)"만 뿅 하고 만들어졌기 때문이다.

🏁 총정리

초스피드 3분 컷 요약
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. Corepack 으로 pnpm 활성화
2. npx 대신 pnpm dlx create-next-app 으로 프로젝트 생성
3. 프로젝트 루트에 .npmrc 파일 만들고 필요한 호이스팅 규칙 추가
4. pnpm install && pnpm dev 로 달리기 시작!
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

이제 손을 한 번 풀어보았으니, "왜 이렇게 빠른지", "왜 굳이 .npmrc 를 써야만 했는지" 그 속사정이 궁금하다면 01. pnpm 멘탈 모델 편 부터 여유롭게 읽어 내려가면 된다.

📝 마무리 퀴즈

Q1. npx create-next-app 대신 pnpm dlx create-next-app을 쓰면 좋은 점은 무엇인가요?

✅ 정답: 프로젝트의 패키지 매니저 흐름을 pnpm으로 맞추고, 일회성 실행도 pnpm store와 같은 방식으로 처리할 수 있습니다.

💡 상세 해설: dlx는 패키지를 프로젝트에 설치하지 않고 한 번 실행할 때 쓰는 명령입니다. 새 프로젝트를 pnpm으로 관리할 거라면 생성 단계부터 이후 설치와 실행까지 pnpm으로 맞추는 편이 덜 헷갈립니다.

Q2. quick start에서 .npmrc를 먼저 추가하는 이유는 무엇인가요?

✅ 정답: Next.js 생태계 일부 도구가 루트 node_modules에서 패키지를 찾는 상황에 대비해 필요한 hoist 규칙을 프로젝트에 기록하기 위해서입니다.

💡 상세 해설: pnpm은 직접 의존성만 루트에 노출하는 엄격한 구조를 씁니다. 일부 도구가 숨은 의존성에 기대고 있으면 로컬에서는 되다가 CI나 다른 팀원 환경에서 깨질 수 있습니다.

Q3. 영철이의 테스트 타임: 프로젝트를 만들고 pnpm dev는 되는데 팀원의 CI에서는 설치가 실패합니다. quick start 단계에서 무엇을 같이 커밋해야 하나요?

✅ 정답: package.json, pnpm-lock.yaml, 프로젝트 .npmrc처럼 설치 결과를 재현하는 파일을 함께 커밋해야 합니다.

💡 상세 해설: lockfile은 정확한 버전을 기록하고, .npmrc는 설치 구조를 바꾸는 팀 규칙입니다. 빠르게 띄우는 것에서 끝내지 않고 팀원이 같은 결과를 재현할 수 있는지까지 확인해야 합니다.

🐣 영철이의 퇴근 일기

오늘은 pnpm을 어렵게 공부하기 전에 일단 Next.js 프로젝트를 하나 띄워봤다. 처음엔 corepack enable, pnpm dlx, .npmrc가 낯선 설정처럼 보였는데, 막상 따라가 보니 전부 "팀원이 같은 설치 결과를 보게 만드는 장치"였다.

framer-motion을 지웠다가 다시 설치했을 때 빠르게 끝나는 것도 신기했다. 하지만 오늘 더 크게 남은 건 속도보다 재현성이었다. 영수 님이 새 스터디 서비스를 급하게 열어야 한다고 해도, 내 노트북에서만 되는 세팅이면 운영 리스크가 된다.

💡 "빠른 설치보다 중요한 건 같은 설치다. lockfile과 프로젝트 설정까지 커밋되어야 팀의 개발 환경이 하나로 맞춰진다."

내일은 pnpm이 왜 이런 구조를 갖는지 더 깊게 봐야겠다. 이제는 명령어를 외우는 대신, node_modules와 lockfile이 어떤 약속을 만드는지 확인하면서 따라갈 생각이다.

🔗 더 알아보기