pnpm 완벽 가이드 | 빠른 패키지 관리자·Monorepo·Workspace·성능·실전 활용

2026년 4월 7일 · 12분 읽기 · 수정 2026년 4월 7일 초급

이 글의 핵심

pnpm으로 효율적인 패키지 관리를 구현하는 완벽 가이드입니다. npm/yarn보다 빠른 설치, Monorepo 관리, Workspace까지 실전 예제로 정리했습니다.

실무 경험 공유: npm에서 pnpm으로 전환하면서, 설치 속도가 3배 빨라지고 디스크 사용량이 70% 감소한 경험을 공유합니다.

들어가며: “npm install이 느려요”

실무 문제 시나리오

시나리오 1: 설치가 너무 느려요
npm은 느립니다. pnpm은 3배 빠릅니다.

시나리오 2: 디스크 공간이 부족해요
중복 패키지가 많습니다. pnpm은 하드링크로 절약합니다.

시나리오 3: Monorepo 관리가 어려워요
Lerna는 복잡합니다. pnpm은 Workspace를 기본 지원합니다.

1. pnpm이란?

핵심 특징

pnpm은 빠르고 효율적인 패키지 관리자입니다.

주요 장점:

빠른 속도: npm보다 3배 빠름
디스크 절약: 하드링크로 70% 절약
엄격한 의존성: Phantom dependencies 방지
Monorepo: Workspace 기본 지원
호환성: npm과 100% 호환

성능 비교:

npm: 60초
yarn: 40초
pnpm: 20초

2. 설치 및 기본 사용

설치

npm install -g pnpm

기본 명령어

# 패키지 설치
pnpm install

# 패키지 추가
pnpm add express
pnpm add -D typescript

# 패키지 제거
pnpm remove express

# 스크립트 실행
pnpm run dev
pnpm dev  # run 생략 가능

# 전역 설치
pnpm add -g typescript

3. Workspace (Monorepo)

프로젝트 구조

my-monorepo/
├── pnpm-workspace.yaml
├── package.json
├── packages/
│   ├── web/
│   │   └── package.json
│   ├── api/
│   │   └── package.json
│   └── shared/
│       └── package.json

pnpm-workspace.yaml

packages:
  - 'packages/*'

루트 package.json

{
  "name": "my-monorepo",
  "private": true,
  "scripts": {
    "dev": "pnpm -r --parallel dev",
    "build": "pnpm -r build",
    "test": "pnpm -r test"
  }
}

패키지 간 의존성

// packages/web/package.json
{
  "name": "web",
  "dependencies": {
    "shared": "workspace:*"
  }
}

// packages/web/src/index.ts
import { utils } from 'shared';

utils.log('Hello from web!');

4. 고급 명령어

필터링

# 특정 패키지만 실행
pnpm --filter web dev

# 특정 패키지와 의존성 실행
pnpm --filter web... build

# 변경된 패키지만 실행
pnpm --filter ...[origin/main] test

병렬 실행

# 모든 패키지 병렬 실행
pnpm -r --parallel dev

# 순차 실행
pnpm -r dev

5. .npmrc 설정

# .npmrc
# 엄격한 peer dependencies
strict-peer-dependencies=true

# 자동 설치
auto-install-peers=true

# 공개 hoist 패턴
public-hoist-pattern[]=*eslint*
public-hoist-pattern[]=*prettier*

# Shamefully hoist (호환성)
shamefully-hoist=false

6. 실전 예제: Turborepo 통합

설치

pnpm add -D turbo

turbo.json

{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "build": {
      "dependsOn": [^build],
      "outputs": ["dist/**", ".next/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "test": {
      "dependsOn": [build],
      "outputs": []
    }
  }
}

실행

pnpm turbo dev
pnpm turbo build
pnpm turbo test

7. CI/CD 최적화

GitHub Actions

# .github/workflows/ci.yml
name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - uses: pnpm/action-setup@v2
        with:
          version: 8
      
      - uses: actions/setup-node@v3
        with:
          node-version: 20
          cache: 'pnpm'
      
      - name: Install dependencies
        run: pnpm install --frozen-lockfile
      
      - name: Run tests
        run: pnpm test
      
      - name: Build
        run: pnpm build

8. 마이그레이션

npm → pnpm

# package-lock.json 삭제
rm package-lock.json

# node_modules 삭제
rm -rf node_modules

# pnpm으로 설치
pnpm install

yarn → pnpm

# yarn.lock 삭제
rm yarn.lock

# node_modules 삭제
rm -rf node_modules

# pnpm으로 설치
pnpm install

정리 및 체크리스트

핵심 요약

pnpm: 빠르고 효율적인 패키지 관리자
속도: npm보다 3배 빠름
디스크 절약: 하드링크로 70% 절약
Workspace: Monorepo 기본 지원
엄격한 의존성: Phantom dependencies 방지
호환성: npm과 100% 호환

구현 체크리스트

같이 보면 좋은 글

Docker Compose 완벽 가이드
Terraform 실전 가이드
Monorepo 아키텍처 가이드

이 글에서 다루는 키워드

pnpm, Package Manager, npm, Monorepo, Workspace, Performance, DevOps

자주 묻는 질문 (FAQ)

Q. npm과 비교하면 어떤가요?

A. pnpm이 3배 빠르고 디스크 사용량이 70% 적습니다. 호환성도 100%입니다.

Q. yarn과 비교하면 어떤가요?

A. pnpm이 더 빠르고 엄격한 의존성 관리를 제공합니다.

Q. 기존 프로젝트에 적용할 수 있나요?

A. 네, lock 파일과 node_modules만 삭제하고 pnpm install하면 됩니다.

Q. Monorepo에 적합한가요?

A. 네, Workspace 기능이 매우 강력합니다. Turborepo와 함께 사용하면 더 좋습니다.