카탈로그

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

Catalog 프로토콜 (catalog:)#

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

pnpm-workspace.yaml
packages:
  - packages/*

# 버전 범위 카탈로그를 정의합니다.
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:
# "catalog:react17"을 통해 참조 가능
react17:
react: ^17.0.2
react-dom: ^17.0.2

# "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:
# "catalog:react17"을 통해 참조 가능
react17:
react: ^17.0.2
react-dom: ^17.0.2

# "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 (기본값) - 종속성을 카탈로그에 자동으로 추가하지 않습니다.

cleanupUnusedCatalogs#

버전 10.15.0에서 추가됨

  • 기본값: false
  • 유형: Boolean

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