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

2026년 3월 20일 수정됨

📋 개요

원리는 나중에! 당장 프로젝트를 시작해야 하는 주니어를 위한 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 설치 방법은 Node.js 에 내장된 Corepack 을 활성화하는 것이다. npm install -g pnpm 보다 버전 충돌이 적고 안전하다.

# 1. Node.js 에 내장된 corepack 활성화 (Node.js 16.13 이상 필요)
corepack enable
 
# 2. 최신 버전의 pnpm 준비
corepack prepare pnpm@latest --activate
 
# 3. 설치 확인
pnpm --version
# 9.x.x 버전이 나오면 성공! 🎉

💡 혹시 권한 에러(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 enable 로 pnpm 활성화
2. npx 대신 pnpm dlx create-next-app 으로 프로젝트 생성
3. 프로젝트 루트에 .npmrc 파일 만들고 호이스팅 5줄 추가 (마법의 주문)
4. pnpm install && pnpm dev 로 달리기 시작!
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

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

📝 마무리 퀴즈

Q1. npx create-next-app 대신 pnpm dlx create-next-app 을 쓰면 좋은 점은?

✅ 정답: pnpm dlx 도 글로벌 캐시 스토어를 활용하기 때문이다. 이전에 다운받은 적 있는 생성기라면 다운로드 없이 즉시 실행되며, 내부적으로 꼬인 임시 캐시 문제 없이 pnpm 의 일관된 방식으로 패키지를 가져온다.

💡 상세 해설:

  • npx 는 항상 npm 레지스트리를 찌르지만 dlx 는 로컬 스토어를 먼저 확인한다.
  • 📌 핵심 기억법: "내 프로젝트가 pnpm 이라면, 일회용 스크립트 실행도 dlx 에게 맡겨라."

🐣 영철이의 퇴근 일기

"pnpm 엄청 어렵고 복잡한 건 줄 알았는데, 영호 방패 삼아서 딱 3분 만에 세팅하니까 솔직히 npm 칠 때랑 별 차이도 안 느껴졌다.

제일 신기했던 건 framer-motion 다시 깔 때였다. 엔터 치자마자 0초 컷으로 설치되는 거 보고 살짝 소름 돋았음... 맨날 npm inst... 치고 화장실 다녀오던 내 시간 돌려내라.

근데 .npmrc 저건 대체 무슨 주문이길래 꼭 써야 한다고 신신당부를 하셨을까? 그냥 하라니까 하긴 했는데... 이제 동작하는 건 확인했으니 내일 출근하면 1편부터 슬슬 읽어봐야겠다. 일단 토이 프로젝트 세팅 끝냈으니 오늘은 맥주 한 캔 까고 넷플릭스 켠다."

🔗 더 알아보기