들어가며

모든 패키지 관리자는 고유의 장단점이 있다. 이 장에서는 npm의 한계를 살펴보고, 이를 해결하기 위해 등장한 Yarn과 pnpm이 각각 어떤 방식으로 문제를 풀었는지 비교한다. 각 도구가 제공하는 특성을 이해하고, 프로젝트의 환경과 상황에 맞는 패키지 관리자를 선택할 수 있도록 정보를 제공하는 것이 목표이다.

npm의 문제점과 한계

2장에서 npm의 구조와 동작 방식을 깊이 살펴보았다. npm은 JavaScript 생태계의 표준 패키지 관리자이지만, 프로젝트 규모가 커질수록 몇 가지 근본적인 문제가 드러난다.

유령 의존성 (Phantom Dependency)

2장에서 다룬 평탄화(hoisting) 작업의 부작용이다. node_modules를 평탄화하면서, package.json에 직접 선언하지 않은 패키지를 코드에서 import하거나 require할 수 있게 된다.

// package.json에 선언하지 않은 패키지인데도 사용 가능
import something from "phantom-package";

디스크 I/O 부하

npm은 동일한 패키지라도 프로젝트마다 node_modules에 개별 복사한다. Node.js는 모듈을 찾기 위해 현재 디렉터리부터 상위로 node_modules를 순회하므로, 구조가 깊어질수록 파일 시스템 접근이 반복되어 I/O 부하가 커진다.

require.resolve.paths("react");
// ["/Users/USER/private/arborist/test/node_modules",
//  "/Users/USER/private/arborist/node_modules",
//  "/Users/USER/private/node_modules",  ...]

실행 위치는 첫 번째 경로이지만, Node.js는 react를 찾을 때까지 여러 디렉터리를 탐색한다. 환경에 따라 탐색 결과가 달라질 수 있어, 실제 서비스에서 의도치 않은 문제를 일으킬 수 있다.

너무 거대한 node_modules

평탄화를 적용하더라도 node_modules의 크기는 매우 크다. 일반적인 React 프로젝트의 node_modules만 해도 수백 MB에 달하는 경우가 흔하다.

• 불필요한 디스크 공간 사용 — 동일한 패키지가 프로젝트마다 중복 저장된다
• 빌드 시간 증가 — 파일 수가 많을수록 번들러와 빌드 도구의 탐색 시간이 늘어난다
• 유효성 검사와 성능 저하 — node_modules 내부의 무결성을 검증하거나 탐색하는 데 시간이 소요된다

변경에 취약한 락 파일

package-lock.json은 동일한 의존성 트리 재현, 설치 속도 최적화, 변경 사항 추적(diff) 등을 위해 존재한다. 하지만 의존성 하나만 바꿔도 diff가 수백~수천 줄에 달해, 사람이 변경 내용을 리뷰하기란 사실상 불가능에 가깝다.

Yarn: 신속하고 안정적인 패키지 관리자

Yarn의 탄생 배경

Facebook(현 Meta)이 npm 기반으로 프로젝트를 운영하면서 의존성 문제를 해결하기 위해 다방면으로 노력했으나, 근본적인 해결을 위해 자체 패키지 관리자를 구현하기에 이르렀다. 2016년에 Yarn이 처음 공개되었다.

yarn이 지적한 npm의 한계

• 인터넷이 없는 환경에서는 npm을 사용할 수 없다. node_modules를 압축해서 버전관리에 포함시키는 방법을 사용했으나 의존성에 조금만 변경이 생겨나도 엄청난 양의 변경 사항이 발생해 부하가 심해졌다.
• 당시 의존성을 완전히 고정하기 위해 shrinkwrap 이라는 명령어가 있었지만 이를 개발자가 의식적으로 실행하지 않으면 누락되기 쉬웠다.
• 단일 의존성을 업데이트해도 관련되지 않은 의존성까지 유의적 버전 규칙을 기반으로 함께 업데이트되는 문제가 있었다. 이로 인해 변경 사항이 불필요하게 커지면서 관리가 어려워졌다.

Yarn의 버전 역사

yarn.lock

Yarn이 생성하는 락 파일이다. npm의 package-lock.json과 유사한 역할을 하지만 몇 가지 차이점이 있다.

• package.json보다 더 정확한 의존성 정보를 기록 -> 버전 범위가 불명확한 package.json의 한계를 보완하기 위해 설계된 것

# yarn.lock 예시 (Yarn Berry 형식)
"react@npm:^18.2.0":
  version: 18.2.0
  resolution: "react@npm:18.2.0"
  dependencies:
    loose-envify: "npm:^1.1.0"
  checksum: 88e38092da8...

[Before] Fastly CDN 경유 (느림)
개발자 ─────────────────→ npm 레지스트리 (Fastly)
 
[Yarn] Cloudflare 리버스 프락시 도입
개발자 → Cloudflare (캐시) → npm 레지스트리
         캐시 히트 시 바로 응답 ↩
 
[After] npm도 Cloudflare 도입
개발자 → Cloudflare → npm 레지스트리  ← 둘 다 빨라짐!
 
→ Yarn은 리버스 프락시를 끄고,
  registry.yarnpkg.com을 npm 레지스트리의 CNAME(별칭)으로 전환

Plug'n'Play (PnP)

Yarn Berry의 가장 혁신적인 기능이다. node_modules 디렉터리를 완전히 제거하고, 의존성 정보를 .pnp.cjs 파일 하나에 담는 방식이다.

기존 방식의 문제

기존 node_modules 방식에서 Node.js가 패키지를 찾는 과정:

1. 현재 디렉터리의 node_modules에서 탐색
2. 없으면 상위 디렉터리의 node_modules로 이동
3. 루트까지 반복 (파일 시스템 I/O가 반복적으로 발생)

이 방식은 탐색이 비효율적이고, 직접 의존성으로 명시하지 않은 패키지도 접근할 수 있는 유령 의존성 문제를 야기한다.

PnP의 동작 원리

yarn start를 실행하면 내부적으로 다음과 동일한 명령이 실행된다:

node -r ./.pnp.cjs index.js

• -r 플래그: --require의 줄임말로, 프로그램 실행 전에 지정한 모듈을 사전 로드(preload) 하도록 지시한다.
• 즉, index.js가 실행되기 전에 .pnp.cjs가 먼저 로드되어 모듈 해석 시스템을 세팅한다.

.pnp.cjs란?

PnP 모드의 핵심 파일이다. yarn.lock과 유사하게 의존성 구조가 담겨 있고, 추가로 각 패키지가 실제 어느 위치에 저장되어 있는지까지 명시되어 있다.

.pnp.cjs     ← 의존성 맵 (패키지 이름 → 실제 위치)
.yarn/cache/ ← 패키지들이 zip 형태로 저장

그렇다면 require('react')처럼 일반적인 모듈 호출 코드가, 어떻게 zip 파일 내부의 패키지를 찾아갈 수 있을까?

핵심은 require 함수 자체를 변조하지 않는다는 점이다. 대신 require가 모듈 경로를 찾을 때 사용하는 Module._resolveFilename 메서드를 변조한다.

[기존 Node.js]
require('react')
  → Module._resolveFilename('react')
  → node_modules/react 탐색 (디렉터리 순회)
 
[PnP 모드]
require('react')
  → Module._resolveFilename('react')  ← .pnp.cjs가 변조
  → .pnp.cjs 맵에서 즉시 위치 조회
  → .yarn/cache/react-xxx.zip 에서 로드

이렇게 탐색을 단일 경로로 한정하면 npm의 두 가지 문제를 동시에 해결할 수 있다:

1. 비효율적 탐색: 디렉터리를 순회하지 않고 맵에서 즉시 조회
2. 유령 의존성: .pnp.cjs에 등록된 패키지만 접근 가능하므로 원천 차단

글로벌 캐시

Yarn은 한 번 다운로드한 패키지를 글로벌 캐시 폴더에 저장해 둔다. 이후 같은 패키지가 필요하면 레지스트리에 다시 접속할 필요 없이 캐시에서 가져온다.

첫 설치:  레지스트리 → 다운로드 → .yarn/berry/cache/ 에 .zip 저장
재설치:   .yarn/berry/cache/ 에서 바로 가져옴 (네트워크 불필요)

• 패키지들은 모두 .zip 압축 형태로 저장된다
• 불안정한 레지스트리 접속에 의존하지 않고, 로컬 캐시 우선 전략을 사용한다
• 설치 과정에서 Fetch → Completed 사이의 네트워크 단계를 생략할 수 있다

비교 정리

PnP모드 끄는법 : .yarnrc.yml 파일에서 nodeLinker: node_modules 설정추가

# .yarnrc.yml - 기존 node_modules 방식으로 폴백
nodeLinker: node-modules

Zero Install

PnP를 기반으로 한 전략으로, 의존성을 Git 저장소에 직접 커밋하는 방식이다.

동작 원리

PnP 모드에서 의존성은 .yarn/cache/ 디렉터리에 zip 파일로 저장된다. 이 zip 파일들은 용량이 상대적으로 작기 때문에, Git 저장소에 커밋해도 크게 부담이 되지 않는다.

프로젝트/
├── .yarn/
│   ├── cache/          ← 의존성 zip 파일들 (Git에 커밋)
│   └── releases/       ← Yarn 바이너리
├── .pnp.cjs            ← 의존성 맵 (Git에 커밋)
├── .yarnrc.yml
└── package.json

장점

단점

플러그인 시스템

Yarn Berry는 플러그인 아키텍처를 채택했다. 핵심 기능 외의 부가 기능을 플러그인으로 분리하여, 필요한 기능만 선택적으로 사용할 수 있다.

플러그인을 통해 가능한 작업:

• 의존성 버전 결정 방식 변경 — 패키지 해석 로직을 커스터마이징
• 패키지 fetcher 추가 — 새로운 프로토콜이나 소스에서 패키지를 가져오도록 확장
• 새로운 명령어 추가 — yarn CLI에 커스텀 명령어 등록
• 새로운 이벤트 등록 — 설치 과정의 특정 시점에 훅을 걸 수 있음

# 플러그인 추가 (Yarn 3.x 이전)
yarn plugin import @yarnpkg/plugin-typescript
 
# Yarn 4.x부터는 모든 공식 플러그인이 기본 내장

주요 공식 플러그인:

대표적인 커뮤니티 플러그인:

Yarn이 생성하는 파일과 디렉터리

# VS Code용 SDK 설치
yarn dlx @yarnpkg/sdks vscode

pnpm: 디스크 공간 절약과 설치 속도의 혁신

pnpm의 탄생 배경

pnpm(performant npm)은 npm과 Yarn Classic이 가진 한계를 극복하기 위해 만들어졌다. 패키지 설치 시 독창적인 방식을 사용하여 중복 저장을 방지하고, 디스크 사용량을 대폭 줄이는 동시에 설치 속도를 향상시킨다. 대규모 프로젝트나 모노레포 환경에서 특히 유용하다.

pnpm은 이 문제들을 하드 링크, 심볼릭 링크, 콘텐츠 어드레서블 스토리지라는 세 가지 핵심 개념으로 해결한다.

pnpm-lock.yaml

pnpm이 사용하는 락 파일이다. npm의 package-lock.json, Yarn의 yarn.lock에 대응한다. 기존 락 파일들의 가독성 부족, diff 비교의 어려움, 비대한 크기 등의 문제를 해결하기 위해 간결한 구조로 설계되었다.

# pnpm-lock.yaml 예시
lockfileVersion: "9.0"
settings:
  autoInstallPeers: true
importers:
  .:
    dependencies:
      react:
        specifier: ^18.2.0
        version: 18.2.0
packages:
  react@18.2.0:
    resolution: { integrity: sha512-... }
    dependencies:
      loose-envify: 1.4.0

글로벌 스토어와 하드 링크

pnpm의 가장 핵심적인 차별점이다. 패키지를 프로젝트마다 복사하는 대신, 글로벌 스토어(~/.pnpm-store)에 한 번만 저장하고 하드 링크로 연결한다.

하드 링크란?

파일 시스템에서 동일한 데이터 블록을 가리키는 또 다른 이름이다. 심볼릭 링크와 달리, 하드 링크는 원본 파일과 완전히 동등한 지위를 가진다.

동작 방식

~/.pnpm-store/                    ← 글로벌 스토어 (한 번만 저장)
├── react@18.2.0/
│   ├── index.js
│   └── ...
└── lodash@4.17.21/
    ├── lodash.js
    └── ...
 
프로젝트A/node_modules/.pnpm/react@18.2.0/
├── index.js  ──────── 하드 링크 ──────── ~/.pnpm-store/react@18.2.0/index.js
└── ...
 
프로젝트B/node_modules/.pnpm/react@18.2.0/
├── index.js  ──────── 하드 링크 ──────── ~/.pnpm-store/react@18.2.0/index.js
└── ...

평탄화되지 않은 node_modules

pnpm은 npm처럼 node_modules를 평탄화하지 않는다. 대신 각 패키지가 정확히 자신의 의존성만 접근할 수 있도록 다음과 같은 전략을 사용한다:

1. ./node_modules에는 직접 의존성만 — package.json의 dependencies에 선언한 패키지만 위치시킨다
2. 실제 파일은 .pnpm에 저장 — 직접 의존성의 실제 파일은 .pnpm/ 디렉터리에 하드 링크로 연결한다
3. 하위 의존성도 .pnpm에 평탄화 — 각 패키지가 필요로 하는 하위 의존성은 ./node_modules/.pnpm/에 평탄화하여 설치한다
4. 하위 의존성 간 참조는 심볼릭 링크 — 각 패키지의 의존성은 .pnpm/ 내에서 심볼릭 링크로 참조한다

node_modules/
├── .pnpm/                          ← 실제 패키지가 저장되는 곳
│   ├── react@18.2.0/
│   │   └── node_modules/
│   │       ├── react/              ← 하드 링크 (글로벌 스토어 → 여기)
│   │       └── loose-envify/       ← 심볼릭 링크 (react의 의존성)
│   └── next@14.0.0/
│       └── node_modules/
│           ├── next/               ← 하드 링크 (글로벌 스토어 → 여기)
│           └── react/              ← 심볼릭 링크 (next의 의존성)
├── react -> .pnpm/react@18.2.0/node_modules/react     ← 심볼릭 링크
└── next -> .pnpm/next@14.0.0/node_modules/next         ← 심볼릭 링크

[문제 상황]
패키지 A의 코드:
  require('lodash')  ← A는 lodash를 dependencies에 선언하지 않음
                       npm에서는 평탄화 덕분에 우연히 동작했음
 
[pnpm에서]
A가 lodash를 선언하지 않았으므로 → 엄격 모드에서는 찾을 수 없음 → 에러!

node_modules/.pnpm/
├── node_modules/           ← 모든 패키지가 평탄화된 폴백 영역
│   ├── lodash/             ← 여기서 찾을 수 있음 (호환성 보장)
│   ├── react/
│   └── ...
├── react@18.2.0/           ← 각 패키지의 격리된 영역
│   └── node_modules/
│       └── react/
└── ...

콘텐츠 어드레서블 스토리지 (CAS)

pnpm의 글로벌 스토어는 콘텐츠 어드레서블 스토리지(Content-Addressable Storage) 방식으로 관리된다. 파일의 내용(content)을 기반으로 해시값을 생성하고, 이 해시값을 주소(address)로 사용하여 저장한다.

~/.pnpm-store/v3/files/
├── 00/
│   ├── 1a2b3c4d5e6f...  ← 파일 내용의 해시가 곧 파일명
│   └── 7a8b9c0d1e2f...
├── 01/
│   └── ...
└── ff/
    └── ...

CAS의 장점

Copy-on-Write (CoW)

pnpm은 글로벌 스토어의 파일을 프로젝트에 연결할 때 기본적으로 하드 링크를 사용하지만, 파일 시스템이 지원하는 경우 Copy-on-Write(CoW), 즉 reflink을 사용할 수도 있다.

CoW는 파일을 복사할 때 실제 데이터 블록을 즉시 복제하지 않고, 원본과 동일한 디스크 블록을 공유하다가 한쪽이 수정될 때 비로소 해당 블록만 분리 복사하는 기법이다.

[일반 복사 (copy)]
원본 파일 ──── 블록 A, B, C     (3개 블록 사용)
복사 파일 ──── 블록 A', B', C'  (3개 블록 추가 → 총 6개)
 
[Copy-on-Write (reflink)]
원본 파일 ──┐
            ├── 블록 A, B, C    (3개 블록만 사용)
복사 파일 ──┘
 
↓ 복사 파일의 블록 B를 수정하면...
 
원본 파일 ──── 블록 A, B, C     (원본 유지)
복사 파일 ──── 블록 A, B", C    (B만 새로 할당 → 총 4개)
              ↑        ↑
              공유      새 블록

하드 링크 vs Copy-on-Write

심볼릭 링크로 구성된 node_modules

pnpm의 node_modules 구조는 두 단계의 링크로 구성된다:

1. 프로젝트 루트 node_modules/ → .pnpm/ 디렉터리의 해당 패키지로의 심볼릭 링크
2. .pnpm/ 내부의 패키지 파일 → 글로벌 스토어로의 하드 링크

[프로젝트 node_modules]
        │
        │ 심볼릭 링크
        ▼
[.pnpm 가상 스토어]
        │
        │ 하드 링크
        ▼
[~/.pnpm-store 글로벌 스토어]

이 구조 덕분에:

• 프로젝트에서는 require('react')처럼 일반적인 방식으로 패키지를 사용 가능
• 내부적으로는 디스크 공간을 최소화
• node_modules를 사용하므로 PnP와 달리 기존 도구와의 호환성 문제가 없음

[장점]

• 의존성 격리 : 각 패키지는 자체 node_modules를 가지고 있어 다른 의존성과 충돌하지 않는다.
• 버전관리의 용이성 : 각 패키지 버전이 독립된 공간을 차지하므로 여러 버전을 관리하기가 용이하다.
• 평탄화된 node_modules의 위험성 회피: 각 의존성은 실제로 자신이 참조하는 의존성에만 접근할 수 있어 평탄화된 node_modules로 인해 발생할 수 있는 문제를 피할 수 있다.

Plug'n'Play 지원

pnpm v9부터 Yarn Berry의 PnP 모드도 지원한다.

# .npmrc
node-linker=pnp

다만, pnpm의 기본 심볼릭 링크 방식이 이미 유령 의존성을 차단하고 디스크 효율성도 뛰어나기 때문에, pnpm에서 PnP를 사용하는 경우는 드물다.

npm, Yarn, pnpm 비교

워크스페이스

세 패키지 관리자 모두 모노레포를 위한 워크스페이스 기능을 지원한다.

# pnpm-workspace.yaml 예시
packages:
  - "packages/*"
  - "apps/*"

하위 패키지 스크립트 실행 (필터 실행)

모노레포에서는 루트가 아닌 특정 하위 패키지의 스크립트를 실행해야 하는 경우가 많다. 각 패키지 관리자마다 이를 위한 명령어가 다르다.

npm

# 특정 패키지의 스크립트 실행
npm run build --workspace=packages/ui
 
# 줄임 표현
npm run build -w packages/ui
 
# 모든 워크스페이스에서 실행
npm run build --workspaces
 
# 스크립트가 없는 패키지는 건너뛰기
npm run build --workspaces --if-present

Yarn Berry

# 특정 패키지의 스크립트 실행 (패키지 이름 기준)
yarn workspace @my-app/ui build
 
# 모든 워크스페이스에서 순차 실행
yarn workspaces foreach run build
 
# 모든 워크스페이스에서 병렬 실행
yarn workspaces foreach -p run build
 
# 의존성 순서를 고려하여 실행 (토폴로지 정렬)
yarn workspaces foreach -pt run build

pnpm

# 패키지 이름으로 필터링
pnpm --filter @my-app/ui build
 
# 디렉터리 경로로 필터링
pnpm --filter ./packages/ui build
 
# 글로브 패턴으로 여러 패키지 실행
pnpm --filter "./packages/*" build
 
# 특정 패키지와 그 의존성까지 포함하여 실행
pnpm --filter @my-app/ui... build
 
# 변경된 패키지만 실행 (Git diff 기반)
pnpm --filter "...[origin/main]" build
 
# 모든 워크스페이스에서 실행
pnpm -r build

pnpm은 워크스페이스에 필요한 기본 기능을 간결하게 제공하는 한편, 버저닝과 같은 복잡한 기능은 changesets나 Rush같은 서드파티 라이브러리르 사용하는 것을 권장한다. pnpm을 기반으로 한 워크스페이스를 운영하려면 이러한 서드파티 라이브러리를 함께 설치해 사용하는 것이 좋다

명령어 비교

벤치마크 테스트

2024년 11월 기준 (책 기준)

npm은 특정 상황을 제외하면 다른 패키지 관리자에 비해 현저히 느리다. Yarn Classic 또한 대부분의 경우 pnpm이나 Yarn Berry에 비해 느리며, Yarn Classic은 보안 패치 외에는 특별한 기능 개선이 이루어지지 않고 있다.

대부분의 경우 Yarn Berry와 pnpm이 가장 빠른 성능을 보였으며, 그중에서도 Yarn Berry가 가장 뛰어난 성능을 나타냈다. pnpm이 하드 링크나 CoW(Copy-on-Write) 작업이 필요한 반면, Yarn Berry는 필요한 의존성을 다운로드하면서 동시에 미리 준비된 .pnp.cjs 파일에 의존성 그래프를 JSON 형식으로 생성하기만 하면 되기 때문이다.

2026년 기준 최신 벤치마크

Bun의 패키지 관리 성능

Bun은 Zig 언어로 작성된 JavaScript 런타임으로, 자체 패키지 관리자를 내장하고 있다. bun install은 기존 패키지 관리자들과 비교했을 때 압도적인 설치 속도를 보여준다.

Bun이 빠른 이유

• 네이티브 바이너리: JavaScript/Node.js 기반이 아닌 Zig + C로 작성되어 시스템 수준의 성능 발휘
• 병렬 다운로드: HTTP 요청을 네이티브 수준에서 극도로 병렬화하여 처리
• 심볼릭 링크 기반: pnpm과 유사하게 글로벌 캐시에서 하드 링크로 연결
• 바이너리 락 파일: bun.lockb는 바이너리 형식으로, 파싱과 직렬화가 텍스트 기반 락 파일보다 빠름

벤치마크 비교 (2026년 기준)

Bun의 한계

종합 비교표