Підтримувані джерела пакунків

pnpm підтримує встановлення пакунків з різних джерел. Ці джерела поділені на дві категорії: надійні джерела та екзотичні джерела.

Екзотичні джерела (такі як репозиторії Git або прямі URL-адреси tar-архівів) можуть створювати ризики для ланцюга постачання, якщо їх використовують перехідні залежності. Ви можете запобігти використанню екзотичних джерел перехідними залежностями, встановивши для blockExoticSubdeps значення true.

Надійні джерела#

Надійні джерела вважаються безпечними для прямих і перехідних залежностей.

Реєстр npm#

Стандартно pnpm add package-name встановить останню версію package-name з npm реєстру.

Якщо команда виконується в робочій області, команда спочатку спробує перевірити, чи інші проєкти у робочій області використовують вказаний пакунок. Якщо так, буде встановлено вже використаний діапазон версій.

Ви також можете встановити пакунки використовуючи:

  • теґ: pnpm add express@nightly
  • версію: pnpm add express@1.0.0
  • діапазон версій: pnpm add express@2 react@">=0.1.0 <0.2.0"

Реєстр JSR#

Щоб встановити пакунки з реєстру JSR, використовуйте префікс протоколу jsr::

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

Це працює так само як встановлення з реєстру npm, але вказує pnpm натомість отримати пакунок з JSR.

crates.io and PyPI#

Added in: v12.4.0 (pnpm v12 only)

A crate: or pypi: prefix asks for a package of another ecosystem, once that ecosystem is enabled in pnpm-workspace.yaml:

pnpm add crate:serde
pnpm add pypi:httpx

Such a dependency is recorded in that ecosystem's own manifest and lockfile, not in package.json or pnpm-lock.yaml. See Cargo dependencies and Python dependencies.

Provisioned tools#

Added in: v12.13.0 (pnpm v12 only)

The tool: protocol asks for a tool pnpm downloads from the tool's own releases instead of from npm: Node.js, Bun, Deno, and Yarn.

pnpm add node@tool:24
pnpm add bun@tool:1.3.0
pnx node@tool:22 --version
pnx yarn@tool:4 --version

yarn@tool:<version> picks Yarn from wherever that line is published, like yarn@<version> does.

runtime: is an alias of tool: and keeps working everywhere it worked before. pnpm-lock.yaml still records these entries with runtime:, such as node@runtime:24.6.0, so lockfiles stay readable by earlier pnpm versions.

Named registries#

A named registry alias resolves a package against a specific registry, regardless of the default one:

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

gh: (GitHub Packages) and npmjs: (the public npm registry) work without configuration. Any other alias must be mapped under namedRegistries in pnpm-workspace.yaml or in the global configuration file (config.yaml).

Робочий простір#

When adding dependencies and working within a workspace, packages will be installed from the configured sources, depending on whether or not linkWorkspacePackages is set, and use of the workspace: range protocol.

Локальна файлова система#

Існує два способи встановлення з локальної файлової системи:

  1. з файлу tar-архіву (.tar, .tar.gz, or .tgz)
  2. з теки

Приклади:

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

pnpm add ./some-directory records the dependency with the link: protocol. pnpm creates a symlink in the current project's node_modules, so it is the same as running pnpm link.

To install a directory as a package instead, use the file: protocol, for example pnpm add file:./some-directory. pnpm copies the directory into the virtual store and installs its dependencies.

Екзотичні джерела#

Екзотичні джерела корисні для розробки, але можуть створювати ризики для ланцюга постачання, якщо їх використовувати перехідними залежностями.

Віддалені архіви#

Аргументом має бути URL-адреса, яка починається з "http://" або "https://".

Приклад:

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

Репозиторій Git#

pnpm add <git remote url>

Installs the package from the Git repository at the given URL. Depending on the repository, pnpm either downloads a source archive from the Git host or clones the repository with Git. See how Git dependencies are resolved.

Ви можете встановити пакунок з Git використовуючи:

  • Останній коміт зі стандартної гілки:
pnpm add kevva/is-positive
  • Git хеш коміту:
pnpm add kevva/is-positive#97edff6f525f192a3f83cea1944765f769ae2678
  • Гілку Git:
pnpm add kevva/is-positive#master
  • Гілку Git відносно refs:
pnpm add zkochan/is-negative#heads/canary
  • Теґ Git:
pnpm add zkochan/is-negative#2.0.1
  • Теґ Git з V-префіксом:
pnpm add andreineculau/npm-publish-git#v0.0.7

Встановлення з репозиторію Git з використанням semver#

Ви можете вказати версію (діапазон) для встановлення за допомогою параметра semver:. Наприклад:

  • Конкретна версія:
pnpm add zkochan/is-negative#semver:1.0.0
  • Конкретна версія з V-префіксом:
pnpm add andreineculau/npm-publish-git#semver:v0.0.7
  • Діапазон версій:
pnpm add kevva/is-positive#semver:^2.0.0
  • Діапазон версій з префіксом V:
pnpm add andreineculau/npm-publish-git#semver:<=v0.0.7

Встановлення з вкладених тек репозиторію Git#

Ви також можете встановити лише вкладену теку з Git-хостингу монорепо за допомогою параметра path:. Наприклад:

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

Встановлення з репозиторію Git з використанням повного URL#

Якщо ви хочете бути точнішими або використовуєте альтернативний хостинг Git, ви можете вказати повну URL-адресу Git:

# 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:

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

Якщо [провайдер]: не вказано, стандартним значенням буде github:.

Встановлення зі сховища Git, комбінуючи різні параметри#

Можна обʼєднати кілька параметрів, розділивши їх символом &. Це може бути корисним для відгалужень монорепо:

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

Встановлюється з гілки beta і лише з вкладеної теки за адресою /packages/simple-react-app.

pnpm also accepts npm's syntax, which separates the parameters with :::

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

How Git dependencies are resolved#

Added in: v12.0.0 (pnpm v12 only)

For repositories on GitHub, GitLab, Bitbucket, and GitHub Gist, the specifier is an identity, not a choice of transport. All of the following name the same dependency and resolve identically:

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

Each resolves through the host's canonical HTTPS URL, and the lockfile records one of two shapes:

  • the host's source archive, a plain tarball download. This is recorded only when an anonymous request for that exact archive URL succeeds, so a recorded archive URL is fetchable by construction.
  • otherwise a git resolution over the canonical HTTPS URL, which every machine that has access to the repository can fetch.

pnpm never records an SSH URL for these hosts. Which transport a given machine uses to reach the host is that machine's Git configuration, not a property of the project.

Using SSH for private repositories#

Configure the rewrite in Git itself, on the machine:

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

pnpm shells out to git, so the rewrite applies to all of pnpm's Git operations automatically. The same holds on CI: give the runner an SSH key and this rewrite, or an HTTPS credential helper. The lockfile is identical either way.

Repositories on other hosts#

A URL that does not point at a known host (a self-hosted GitLab, Gitea, or any internal Git server) is kept exactly as written, transport included. For those, the URL is the identity. URLs with credentials embedded in them are also kept verbatim, and never resolve to a host archive.

інформація

Existing lockfile entries are left untouched. The rules above apply when an entry is added or re-resolved, and pnpm update <package> re-records an SSH URL over HTTPS.

How a Git dependency is built#

Added in: v12.0.0-rc.6 (pnpm v12 only)

A Git-hosted dependency that ships sources rather than a built package has to be prepared (its dependencies installed and its build script run) before it can be installed. pnpm prepares it with the package manager the dependency asks for. See Preparing a git-hosted dependency.