pnpm workspace + catalogs — 모노레포 의존성 버전 한 곳에서

모노레포에서 React, TypeScript, ESLint 같은 공통 의존성을 여러 패키지가 쓸 때, 버전을 일치시키는 게 의외로 까다롭습니다. pnpm 9에서 추가된 catalogs는 의존성 버전을 한 곳에 모아두고, 각 패키지에서 catalog:로 참조하게 해줍니다. 버전 drift가 자연스럽게 사라집니다.

1. 기본 설정

1# pnpm-workspace.yaml
2packages:
3  - 'apps/*'
4  - 'packages/*'
5
6catalog:
7  react: ^18.3.1
8  react-dom: ^18.3.1
9  typescript: ^5.5.4
10  zod: ^3.23.8

각 패키지의 package.json에서는 catalog: 프로토콜로 참조합니다.

1{
2  "name": "@app/web",
3  "dependencies": {
4    "react": "catalog:",
5    "react-dom": "catalog:",
6    "zod": "catalog:"
7  },
8  "devDependencies": {
9    "typescript": "catalog:"
10  }
11}

pnpm install 시점에 catalog의 실제 버전으로 해석됩니다.

2. 여러 카탈로그 (named catalogs)

용도별로 카탈로그를 나눌 수 있습니다.

1catalogs:
2  legacy:
3    react: ^17.0.2
4    react-dom: ^17.0.2
5  modern:
6    react: ^18.3.1
7    react-dom: ^18.3.1

1{
2  "dependencies": {
3    "react": "catalog:modern"
4  }
5}

마이그레이션 중 일부 패키지만 새 버전으로 옮길 때 유용합니다.

3. 버전 업그레이드

pnpm-workspace.yaml의 catalog 값만 바꾸면 모든 패키지가 같이 올라갑니다.

1catalog:
2  react: ^19.0.0  # 17 → 18 → 19

각 패키지의 package.json을 수정하지 않아도 됩니다.

4. 명시적 버전과의 충돌 방지

같은 의존성이 일부 패키지에선 catalog, 일부에선 직접 버전이면 lockfile에서 두 버전이 모두 설치됩니다.

1// 권장 X
2"react": "^18.2.0"     // 일부 패키지
3"react": "catalog:"    // 다른 패키지

가능하면 모든 패키지를 catalog로 통일합니다. pnpm dedupe로 정리할 수 있지만, 처음부터 일관되게 쓰는 게 깔끔합니다.

5. 다른 도구 비교

방법	단점
package.json#engines.npm 강제	버전 일치 보장 X
syncpack 같은 외부 도구	CI에서 검증 필요, 코드 수정도 직접
pnpm catalogs	pnpm 안에서 자동, lockfile 일관

6. 주의할 점

• pnpm 9.5.0 이상이 필요합니다. CI에서 pnpm 버전을 명시적으로 지정.
• npm/yarn에서 동작하지 않습니다. 모노레포 패키지 매니저를 pnpm으로 통일.
• catalog: 참조는 publish 시점에 실제 버전으로 변환됩니다 (publishConfig.directory 또는 pnpm publish). 단독 publish가 아니라면 신경 쓸 일이 적습니다.
• pnpm outdated가 catalog 항목을 인식합니다. 업그레이드 검토에 활용.

7. 정리

Before	After
패키지마다 React 버전 따로 관리	pnpm-workspace.yaml에 한 줄
일부만 18로 올렸다 buggy	한 번 바꾸면 모두 따라옴
dedupe 자주 실행	처음부터 한 버전만 설치

작은 모노레포라도 catalogs를 쓰면 의존성이 흩어지는 걸 막을 수 있습니다. 도입 비용이 거의 0이고, 효과는 월 단위로 누적됩니다.

참고: pnpm 9 — Catalogs / pnpm-workspace.yaml 문서.