지원되는 패키지 소스

pnpm은 다양한 소스에서 패키지를 설치하는 것을 지원합니다. 이러한 소스는 신뢰할 수 있는 소스와 특이한 소스의 두 가지 범주로 나뉩니다.

특이한 소스(Git 저장소나 직접 tarball URL 등)는 전이 종속성에서 사용될 때 공급망 위험을 초래할 수 있습니다. blockExoticSubdeps를 true로 설정하면 전이 종속성이 특이한 소스를 사용하지 못하도록 막을 수 있습니다.

신뢰할 수 있는 소스#

신뢰할 수 있는 소스는 직접 종속성과 전이 종속성 모두에 안전한 것으로 간주됩니다.

npm 레지스트리#

pnpm add package-name은 기본적으로 npm 레지스트리에서 package-name의 최신 버전을 설치합니다.

워크스페이스에서 실행하는 경우, 명령은 먼저 워크스페이스에 있는 다른 프로젝트가 지정된 패키지를 사용하는지 여부를 확인합니다. 이 경우, 이미 사용된 버전이 설치됩니다.

다음을 통해 패키지를 설치할 수도 있습니다.

  • 태그: pnpm add express@nightly
  • 버전: pnpm add express@1.0.0
  • 버전 범위: pnpm add express@2 react@">=0.1.0 <0.2.0"

JSR 레지스트리#

버전 10.9.0에서 추가됨

JSR 레지스트리에서 패키지를 설치하려면 jsr: 프로토콜 접두사를 사용하세요:

pnpm add jsr:@hono/hono
pnpm add jsr:@hono/hono@4
pnpm add jsr:@hono/hono@latest

이것은 npm에서 설치하는 것과 동일하게 작동하지만 JSR을 통해 패키지를 확인하도록 pnpm에 지시합니다.

이름이 지정된 레지스트리#

추가된 버전: v11.1.0

이름이 지정된 레지스트리 별칭은 기본 레지스트리와 관계없이 특정 레지스트리에서 패키지를 해석합니다:

pnpm add work:@corp/lib@^2.0.0
pnpm add gh:@my-org/private-pkg
pnpm add npmjs:left-pad

gh:(GitHub Packages)와 v11.20.0부터 npmjs:(공개 npm 레지스트리)는 설정 없이 작동합니다. 그 외의 별칭은 pnpm-workspace.yaml의 namedRegistries 아래에, 또는 v11.11.0부터는 글로벌 설정 파일(config.yaml)에 매핑해야 합니다.

작업 공간#

workspace 내에서 종속성을 추가하고 작업할 때는 linkWorkspacePackages의 설정 여부와 workspace: range protocol의 사용 여부에 따라 구성된 소스에서 패키지가 설치된다는 점에 유의하세요.

로컬 파일 시스템#

로컬 파일 시스템에서 설치하는 방법에는 두 가지가 있습니다.

  1. tarball 파일(.tar, .tar.gz 또는 .tgz)에서
  2. 디렉토리에서 설치

예시:

pnpm add ./package.tar.gz
pnpm add ./some-directory

디렉터리에서 설치하면 현재 프로젝트의 node_modules에 심볼릭 링크가 생성되므로 pnpm link를 실행하는 것과 같습니다.

특이한 소스#

특이한 소스는 개발에 유용하지만 전이 종속성에서 사용될 때 공급망 위험을 초래할 수 있습니다.

원격 tarball#

인수는 "http://" 또는 "https://"로 시작하는 가져올 수 있는 URL이어야 합니다.

예시:

pnpm add https://github.com/indexzero/forever/tarball/v0.5.6

Git 저장소#

pnpm add <git remote url>

지정된 URL의 Git 저장소에서 패키지를 설치합니다. 저장소에 따라 pnpm은 Git 호스트에서 소스 아카이브를 다운로드하거나 Git으로 저장소를 클론합니다 — Git 종속성이 해석되는 방식을 참고하세요.

다음을 통해 Git에서 패키지를 설치할 수 있습니다:

  • 기본 브랜치의 최신 커밋:
pnpm add kevva/is-positive
  • Git 커밋 해시:
pnpm add kevva/is-positive#97edff6f525f192a3f83cea1944765f769ae2678
  • Git 브랜치:
pnpm add kevva/is-positive#master
  • 깃 브랜치 참조:
pnpm add zkochan/is-negative#heads/canary
  • 깃 태그:
pnpm add zkochan/is-negative#2.0.1
  • V-접두사가 붙은 Git 태그:
pnpm add andreineculau/npm-publish-git#v0.0.7

시맨틱 버전을 사용하여 Git 저장소로부터 설치#

semver: 매개변수를 사용하여 설치할 버전(범위)을 지정할 수 있습니다. 예시:

  • 엄격한 semver:
pnpm add zkochan/is-negative#semver:1.0.0
  • V-접두사가 붙은 엄격한 semver:
pnpm add andreineculau/npm-publish-git#semver:v0.0.7
  • Semver 범위를 통한 설치:
pnpm add kevva/is-positive#semver:^2.0.0
  • V-접두사가 붙은 semver 버전 범위:
pnpm add andreineculau/npm-publish-git#semver:<=v0.0.7

Git 저장소의 하위 디렉터리에서 설치하기#

path: 매개변수를 사용하여 Git에 호스팅된 모노레포에서 하위 디렉터리만 설치할 수도 있습니다. 예를 들어:

pnpm add RexSkz/test-git-subfolder-fetch#path:/packages/simple-react-app

전체 URL을 통해 Git 저장소에서 설치하기#

더 명시적으로 지정하고 싶거나 다른 Git 호스팅을 사용하는 경우, 전체 Git URL을 작성할 수 있습니다:

# git+ssh
pnpm add git+ssh://git@github.com:zkochan/is-negative.git#2.0.1

# https
pnpm add https://github.com/zkochan/is-negative.git#2.0.1

호스팅 제공자 약어를 사용하여 Git 저장소에서 설치하기#

특정 Git 제공자에 대해 프로토콜 약어 [provider]:를 사용할 수 있습니다:

pnpm add github:zkochan/is-negative
pnpm add bitbucket:pnpmjs/git-resolver
pnpm add gitlab:pnpm/git-resolver

[provider]:를 생략하면 기본값은 github:입니다.

여러 매개변수를 결합하여 Git 저장소에서 설치#

여러 매개변수를 &로 구분하여 결합할 수 있습니다. 이는 모노레포를 포크(fork)한 경우에 유용할 수 있습니다:

pnpm add RexSkz/test-git-subdir-fetch.git#beta\&path:/packages/simple-react-app

beta 브랜치에서 /packages/simple-react-app에 있는 하위 디렉터리만 설치합니다.

Git 종속성이 해석되는 방식#

추가된 버전: v12.0.0 (pnpm v12 전용)

GitHub, GitLab, Bitbucket의 저장소에서 지정자는 전송 방식의 선택이 아니라 식별자입니다. 다음은 모두 같은 종속성을 가리키며 동일하게 해석됩니다:

kevva/is-positive
github:kevva/is-positive
git+https://github.com/kevva/is-positive.git
git+ssh://git@github.com/kevva/is-positive.git

각각은 호스트의 표준 HTTPS URL을 통해 해석되며, lockfile에는 다음 두 가지 형태 중 하나가 기록됩니다:

  • 호스트의 소스 아카이브, 즉 일반 tarball 다운로드. 이는 해당 아카이브 URL에 대한 익명 요청이 성공한 경우에만 기록되므로, 기록된 아카이브 URL은 구조적으로 항상 가져올 수 있습니다.
  • 그렇지 않으면 표준 HTTPS URL을 통한 git 해석이 기록되며, 저장소에 접근할 수 있는 모든 머신에서 이를 가져올 수 있습니다.

pnpm은 이러한 호스트에 대해 SSH URL을 기록하지 않습니다. 특정 머신이 호스트에 접근할 때 사용하는 전송 방식은 프로젝트의 속성이 아니라 해당 머신의 Git 설정에 따라 결정됩니다.

pnpm 11은 지정자의 전송 방식을 기록된 URL의 일부로 유지하지만, v11.21.0부터는 지정자 자체가 SSH를 요청하는 경우(git+ssh:// 또는 git@host:...)에만 SSH URL을 기록합니다: owner/repo와 같은 약어는 HTTPS로 해석되고 기록되므로, SSH 키가 있는 머신에서 작성된 lockfile도 SSH 키가 없는 CI 러너에서 설치할 수 있습니다. 이전 버전의 pnpm이 기록한 SSH URL은 pnpm update <package>으로 HTTPS로 다시 기록할 수 있습니다.

비공개 저장소에 SSH 사용하기#

Git 자체에서, 해당 머신에 재작성 규칙을 설정하세요:

git config --global url."git@github.com:".insteadOf https://github.com/

pnpm은 git을 호출하므로 이 재작성은 pnpm의 모든 Git 작업에 자동으로 적용됩니다. CI에서도 마찬가지입니다: 러너에 SSH 키와 이 재작성 설정을 제공하거나 HTTPS 자격 증명 헬퍼를 제공하세요 — 어느 쪽이든 lockfile은 동일합니다.

다른 호스트의 저장소#

알려진 호스트를 가리키지 않는 URL(자체 호스팅 GitLab, Gitea 또는 모든 내부 Git 서버)은 전송 방식을 포함하여 작성된 그대로 유지됩니다 — 이러한 경우에는 URL 자체가 식별자입니다. 자격 증명이 포함된 URL도 그대로 유지되며, 호스트 아카이브로 해석되지 않습니다.

정보

이전 버전인 pnpm v11 이하에서는 해석 시 네트워크를 탐색하여 HTTPS와 SSH 중 하나를 결정했습니다. 이로 인해 설치를 실행한 머신에서 우연히 작동한 전송 방식이 기록될 수 있었습니다 — 대부분의 경우 ssh:// URL이 기록되어 SSH 키가 없는 CI 러너에서 실패했습니다. pnpm v12에서는 이러한 탐색이 제거되었습니다. 기존 lockfile 항목은 그대로 유지되며, 위의 규칙은 항목이 추가되거나 다시 해석될 때 적용됩니다.

Git 종속성이 빌드되는 방식#

추가된 버전: v12.0.0-rc.6 (pnpm v12 전용)

빌드된 패키지 대신 소스를 제공하는 Git 호스팅 종속성은 설치하기 전에 준비 과정이 필요합니다 — 해당 종속성을 설치하고 빌드 스크립트를 실행해야 합니다. pnpm은 호스트에 올바른 패키지 관리자가 있다고 가정하지 않고, 종속성 자체가 요구하는 패키지 관리자로 이를 준비합니다:

  • 종속성 자체의 packageManager / devEngines.packageManager 고정이 우선합니다 — 작성자가 테스트하는 대상이 바로 그것이기 때문입니다;
  • 고정이 없으면, 종속성이 포함한 lockfile이 패키지 관리자를 지정합니다. yarn.lock은 어떤 Yarn 계열인지도 나타냅니다: Yarn Berry는 작성하는 모든 lockfile에 __metadata:를 기록하며 두 계열은 서로의 lockfile을 읽을 수 없으므로, Classic lockfile은 더 이상 Berry로 설치되지 않습니다.

종속성이 버전을 고정했거나 호스트가 종속성의 요구 사항을 충족할 수 없는 경우, pnpm은 해당 패키지 관리자를 제공합니다. 따라서 Yarn으로 빌드된 저장소는 pnpm만 있는 머신에서도 설치되며, 빌드가 호출할 수 있는 모든 이름으로 적합한 패키지 관리자를 이미 갖춘 호스트는 자체 패키지 관리자를 계속 사용합니다.