카탈로그

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

The catalog protocol (catalog:)#

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

packages:
  - packages/*

# 버전 범위 카탈로그를 정의합니다.
catalog:
  react: ^18.3.1
  redux: ^5.0.1

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

{
  "name": "@example/app",
  "dependencies": {
    "react": "catalog:",
    "redux": "catalog:"
  }
}

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

{
  "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 파일을 작성할 때 중복을 줄여주며, 다음과 같은 장점을 몇 가지 제공합니다:

• Maintain unique versions: It's usually desirable to have only one version of a dependency in a workspace. 카탈로그를 사용하면 유지 관리가 더 쉬워집니다. 중복된 종속성은 런타임에 충돌을 일으켜 버그를 일으킬 수 있습니다. 번들러를 사용할 때 중복은 번들 크기도 증가시킵니다.
• Easier upgrades: When upgrading a dependency, only the catalog entry in pnpm-workspace.yaml needs to be edited rather than all package.json files using that dependency. This saves time. Only one line needs to be changed instead of many.
• Fewer merge conflicts: Since package.json files do not need to be edited when upgrading a dependency, git merge conflicts no longer happen in these files.

Defining catalogs#

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

1. (단수) catalog 필드를 사용하여 default라는 이름의 카탈로그를 만듭니다.
2. (복수) catalogs 필드를 사용하여 임의로 이름이 지정된 카탈로그를 만듭니다.

pnpx codemod pnpm/catalog

Default catalog#

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

catalog:
  react: ^18.2.0
  react-dom: ^18.2.0

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

Named catalogs#

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

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

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

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

Workspace dependencies in a catalog#

Added in: v11.26.0

A catalog entry may hold a workspace: range, so the version a workspace dependency is linked by is written once too:

catalog:
  '@example/utils': workspace:^

{
  "name": "@example/app",
  "dependencies": {
    "@example/utils": "catalog:"
  }
}

pnpm expands the catalog: reference to workspace:^ and then links the workspace project, exactly as if the package.json had declared workspace:^ itself. On publish both protocols are replaced, so the example above ships as "^1.4.0" when @example/utils is at 1.4.0.

게시#

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

예시,

{
  "name": "@example/components",
  "dependencies": {
    "react": "catalog:react18"
  }
}

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

{
  "name": "@example/components",
  "dependencies": {
    "react": "^18.3.1"
  }
}

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

설정#

catalogMode#

버전 10.12.1에서 추가됨

• 기본값: manual
• 타입: manual, strict, prefer

pnpm add를 실행할 때 의존성을 기본 카탈로그에 추가할지, 추가한다면 어떤 방식으로 추가할지를 제어합니다. 세 가지 모드가 있습니다:

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

Since v11.26.0, a specifier that names a location rather than a version is never moved into a catalog: local paths, local tarballs, tarball URLs, and workspace:<path> ranges stay in the package.json that declares them. Such a specifier is resolved relative to its own project, so one catalog entry could not mean the same directory for every project that references it.

catalogPrune#

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

• 기본값: false
• 타입: Boolean

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

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