카탈로그

"Catalogs"는 종속성 버전 범위를 재사용 가능한 상수로 정의하기 위한 워크스페이스 기능입니다. 카탈로그에 정의된 상수는 나중에 package.json 파일에서 참조할 수 있습니다.

Catalog 프로토콜 (catalog:)#

pnpm-workspace.yaml에 카탈로그가 정의되면,

pnpm-workspace.yaml
packages:
  - packages/*

# Define a catalog of version ranges.
catalog:
  react: ^18.3.1
  redux: ^5.0.1

버전 범위 자체 대신 catalog: 프로토콜을 사용할 수 있습니다.

packages/example-app/package.json
{
  "name": "@example/app",
  "dependencies": {
    "react": "catalog:",
    "redux": "catalog:"
  }
}

이는 버전 범위(예: ^18.3.1)를 직접 작성하는 것과 같습니다.

packages/example-app/package.json
{
  "name": "@example/app",
  "dependencies": {
    "react": "^18.3.1",
    "redux": "^5.0.1"
  }
}

catalog: 프로토콜은 다음 필드에서 사용할 수 있습니다:

  • package.json:
    • dependencies
    • devDependencies
    • peerDependencies
    • optionalDependencies
  • pnpm-workspace.yaml
    • overrides

catalog: 프로토콜은 사용할 카탈로그를 지정하기 위해 콜론 뒤에 선택적으로 이름을 붙일 수 있습니다 (예: catalog:name). 이름을 생략하면 기본 카탈로그가 사용됩니다.

상황에 따라 catalog: 프로토콜은 버전 범위를 직접 작성하는 것에 비해 몇 가지 장점이 있으며, 이에 대해서는 다음에 자세히 설명합니다.

장점#

워크스페이스(즉, 모노레포 또는 다중 패키지 저장소)에서는 동일한 종속성을 여러 패키지가 사용하는 것이 일반적입니다. 카탈로그는 package.json 파일을 작성할 때 중복을 줄여 주며, 그 과정에서 다음과 같은 이점을 제공합니다:

  • 고유한 버전 유지 — 일반적으로 워크스페이스에는 종속성의 버전이 하나만 있는 것이 바람직합니다. 카탈로그를 사용하면 이를 더 쉽게 유지 관리할 수 있습니다. 중복된 종속성은 런타임에 충돌하여 버그를 일으킬 수 있습니다. 또한 번들러를 사용할 때 중복은 크기를 증가시킵니다.
  • 더 쉬운 업그레이드 — 종속성을 업그레이드할 때, 해당 종속성을 사용하는 모든 package.json 파일 대신 pnpm-workspace.yaml의 카탈로그 항목만 수정하면 됩니다. 이를 통해 시간을 절약할 수 있습니다 — 여러 줄 대신 한 줄만 변경하면 됩니다.
  • 더 적은 병합 충돌 — 종속성을 업그레이드할 때 package.json 파일을 수정할 필요가 없으므로, 이러한 파일에서 git 병합 충돌이 더 이상 발생하지 않습니다.

카탈로그 정의하기#

카탈로그는 pnpm-workspace.yaml 파일에 정의됩니다. 카탈로그를 정의하는 방법은 두 가지가 있습니다.

  1. (단수형) catalog 필드를 사용하여 default라는 이름의 카탈로그를 생성합니다.
  2. (복수형) catalogs 필드를 사용하여 임의의 이름을 가진 카탈로그를 생성합니다.

팁

카탈로그를 사용하도록 마이그레이션하려는 기존 워크스페이스가 있다면, 다음 codemod를 사용할 수 있습니다:

pnpx codemod pnpm/catalog

기본 카탈로그#

최상위 catalog 필드를 사용하면 default라는 이름의 카탈로그를 정의할 수 있습니다.

pnpm-workspace.yaml
catalog:
  react: ^18.2.0
  react-dom: ^18.2.0

이러한 버전 범위는 catalog:default를 통해 참조할 수 있습니다. 기본 카탈로그에 한해 특별한 catalog: 약어도 사용할 수 있습니다. catalog:는 catalog:default로 확장되는 약어라고 생각하면 됩니다.

이름이 지정된 카탈로그#

임의로 선택한 이름을 가진 여러 카탈로그를 catalogs 키 아래에 구성할 수 있습니다.

pnpm-workspace.yaml
catalogs:
  # Can be referenced through "catalog:react17"
  react17:
    react: ^17.0.2
    react-dom: ^17.0.2

  # Can be referenced through "catalog:react18"
  react18:
    react: ^18.2.0
    react-dom: ^18.2.0

기본 카탈로그는 여러 개의 이름이 지정된 카탈로그와 함께 정의할 수 있습니다. 이는 종속성을 점진적으로 새 버전으로 마이그레이션하는 대규모 다중 패키지 저장소에서 유용할 수 있습니다.

pnpm-workspace.yaml
catalog:
  react: ^16.14.0
  react-dom: ^16.14.0

catalogs:
  # Can be referenced through "catalog:react17"
  react17:
    react: ^17.0.2
    react-dom: ^17.0.2

  # Can be referenced through "catalog:react18"
  react18:
    react: ^18.2.0
    react-dom: ^18.2.0

게시#

pnpm publish 또는 pnpm pack을 실행하면 catalog: 프로토콜이 제거됩니다. 이는 workspace: 프로토콜과 유사하며, 해당 프로토콜도 게시 시 대체됩니다.

예시,

packages/example-components/package.json
{
  "name": "@example/components",
  "dependencies": {
    "react": "catalog:react18",
  }
}

게시 시 다음과 같이 변환됩니다.

packages/example-components/package.json
{
  "name": "@example/components",
  "dependencies": {
    "react": "^18.3.1",
  }
}

catalog: 프로토콜 대체 과정 덕분에 @example/components 패키지를 다른 워크스페이스나 패키지 관리자에서도 사용할 수 있습니다.

설정#

catalogMode#

버전 10.12.1에서 추가됨

  • 기본값: manual
  • 유형: manual, strict, prefer

pnpm add를 실행할 때 종속성을 기본 카탈로그에 추가할지 여부와 추가 방식을 제어합니다. 세 가지 모드가 있습니다:

  • strict - 카탈로그의 종속성 버전만 허용합니다. 카탈로그의 버전 범위를 벗어난 종속성을 추가하면 오류가 발생합니다.
  • prefer - 카탈로그 버전을 우선하지만, 호환되는 버전을 찾지 못하면 직접 종속성으로 대체합니다.
  • manual (기본값) - 종속성을 카탈로그에 자동으로 추가하지 않습니다.

catalogPrune#

추가된 버전: v11.22.0 (v10.15.0부터는 cleanupUnusedCatalogs라는 이름으로 제공)

  • 기본값: false
  • 타입: Boolean

true로 설정하면, pnpm은 설치 중에 사용되지 않는 카탈로그 항목을 제거합니다.

cleanupUnusedCatalogs는 사용 중단된 이 설정의 이전 이름이며 계속 동작합니다; 둘 다 설정된 경우 catalogPrune이 우선합니다.