Settings (pnpm-workspace.yaml)

pnpm gets its configuration from the command line, environment variables, pnpm-workspace.yaml, and .npmrc files.

The pnpm config command can be used to read and edit the contents of the project and global configuration files.

The relevant configuration files are:

• Per-project configuration file: /path/to/my/project/pnpm-workspace.yaml
• Global configuration file: ~/.config/pnpm/rc (an INI-formatted list of key = value parameters)

нотатка

Authorization-related settings are handled by npm's configuration system. So, pnpm config set registry=<value> will actually save the setting to npm's global configuration file.

Values in the configuration files may contain env variables using the ${NAME} syntax. Змінні env також можуть бути вказані зі стандартними значеннями. Using ${NAME-fallback} will return fallback if NAME isn't set. ${NAME:-fallback} will return fallback if NAME isn't set, or is an empty string.

Dependency Resolution

overrides

This field allows you to instruct pnpm to override any dependency in the dependency graph. Це корисно для того, щоб змусити всі ваші пакунки використовувати одну версію залежності, перенести виправлення, замінити залежність форком або видалити невикористовувану залежність.

Note that the overrides field can only be set at the root of the project.

An example of the overrides field:

overrides:
  "foo": "^1.0.0"
  "quux": "npm:@myorg/quux@^1.0.0"
  "bar@^2.1.0": "3.0.0"
  "qar@1>zoo": "2"

You may specify the package the overridden dependency belongs to by separating the package selector from the dependency selector with a ">", for example qar@1>zoo will only override the zoo dependency of qar@1, not for any other dependencies.

Перевизначення можна визначити як посилання на специфікацію прямої залежності. This is achieved by prefixing the name of the dependency with a $:

package.json

{
  "dependencies": {
    "foo": "^1.0.0"
  }
}

pnpm-workspace.yaml

overrides:
  foo: "$foo"

Пакунок, на який посилаються, не обовʼязково повинен збігатися з пакунком, на який посилається перевизначений:

pnpm-workspace.yaml

overrides:
  bar: "$foo"

If you find that your use of a certain package doesn't require one of its dependencies, you may use - to remove it. For example, if package foo@1.0.0 requires a large package named bar for a function that you don't use, removing it could reduce install time:

overrides:
  "foo@1.0.0>bar": "-"

This feature is especially useful with optionalDependencies, where most optional packages can be safely skipped.

packageExtensions

The packageExtensions fields offer a way to extend the existing package definitions with additional information. For example, if react-redux should have react-dom in its peerDependencies but it has not, it is possible to patch react-redux using packageExtensions:

packageExtensions:
  react-redux:
    peerDependencies:
      react-dom: "*"

The keys in packageExtensions are package names or package names and semver ranges, so it is possible to patch only some versions of a package:

packageExtensions:
  react-redux@1:
    peerDependencies:
      react-dom: "*"

The following fields may be extended using packageExtensions: dependencies, optionalDependencies, peerDependencies, and peerDependenciesMeta.

A bigger example:

packageExtensions:
  express@1:
    optionalDependencies:
      typescript: "2"
  fork-ts-checker-webpack-plugin:
    dependencies:
      "@babel/core": "1"
    peerDependencies:
      eslint: ">= 6"
    peerDependenciesMeta:
      eslint: {
        optional: true

підказка

Together with Yarn, we maintain a database of packageExtensions to patch broken packages in the ecosystem. If you use packageExtensions, consider sending a PR upstream and contributing your extension to the @yarnpkg/extensions database.

allowedDeprecatedVersions

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

Приклад:

allowedDeprecatedVersions:
  express: "1"
  request: "*"

With the above configuration pnpm will not print deprecation warnings about any version of request and about v1 of express.

updateConfig

updateConfig.ignoreDependencies

Sometimes you can't update a dependency. For instance, the latest version of the dependency started to use ESM but your project is not yet in ESM. Annoyingly, such a package will be always printed out by the pnpm outdated command and updated, when running pnpm update --latest. However, you may list packages that you don't want to upgrade in the ignoreDependencies field:

updateConfig: {
  ignoreDependencies:
  - load-json-file

Patterns are also supported, so you may ignore any packages from a scope: @babel/*.

supportedArchitectures

You can specify architectures for which you'd like to install optional dependencies, even if they don't match the architecture of the system running the install.

For example, the following configuration tells to install optional dependencies for Windows x64:

supportedArchitectures:
  os:
  - win32
  cpu:
  - x64

Whereas this configuration will install optional dependencies for Windows, macOS, and the architecture of the system currently running the install. It includes artifacts for both x64 and arm64 CPUs:

supportedArchitectures:
  os:
  - win32
  - darwin
  - current
  cpu:
  - x64
  - arm64

Additionally, supportedArchitectures also supports specifying the libc of the system.

ignoredOptionalDependencies

If an optional dependency has its name included in this array, it will be skipped. Наприклад:

ignoredOptionalDependencies:
- fsevents
- "@esbuild/*"

Налаштування підйому залежностей

hoist

• Default: true
• Type: boolean

When true, all dependencies are hoisted to node_modules/.pnpm/node_modules. This makes unlisted dependencies accessible to all packages inside node_modules.

hoistWorkspacePackages

• Default: true
• Type: boolean

When true, packages from the workspaces are symlinked to either <workspace_root>/node_modules/.pnpm/node_modules or to <workspace_root>/node_modules depending on other hoisting settings (hoistPattern and publicHoistPattern).

hoistPattern

• Default: ['*']
• Type: string[]

Tells pnpm which packages should be hoisted to node_modules/.pnpm/node_modules. Стандартно, всі пакунки буде піднято — однак, якщо ви знаєте, що лише деякі пакунки мають фантомні залежності, ви можете скористатися цим параметром, щоб підняти лише фантомні залежності (рекомендується).

Наприклад:

hoistPattern:
- "*eslint*"
- "*babel*"

You may also exclude patterns from hoisting using !.

Наприклад:

hoistPattern:
- "*types*"
- "!@types/react"

publicHoistPattern

• Стандартно: []
• Type: string[]

Unlike hoistPattern, which hoists dependencies to a hidden modules directory inside the virtual store, publicHoistPattern hoists dependencies matching the pattern to the root modules directory. Підняття до кореневої теки модулів означає, що код застосунку матиме доступ до фантомних залежностей, навіть якщо вони неправильно змінять стратегію розвʼязання.

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

Наприклад:

publicHoistPattern:
- "*plugin*"

Note: Setting shamefullyHoist to true is the same as setting publicHoistPattern to *.

You may also exclude patterns from hoisting using !.

Наприклад:

publicHoistPattern:
- "*types*"
- "!@types/react"

shamefullyHoist

• Default: false
• Type: Boolean

Стандартно pnpm створює напівсувору теку node_modules, тобто залежності мають доступ до неоголошених залежностей, а модулі поза межами node_modules — ні. За такої схеми більшість пакунків в екосистемі працюють без проблем. However, if some tooling only works when the hoisted dependencies are in the root of node_modules, you can set this to true to hoist them for you.

Параметри модулів

modulesDir

• Default: node_modules
• Type: path

The directory in which dependencies will be installed (instead of node_modules).

nodeLinker

• Default: isolated
• Type: isolated, hoisted, pnp

Визначає, який компонувальник слід використовувати для встановлення пакунків Node.

• isolated - dependencies are symlinked from a virtual store at node_modules/.pnpm.
• hoisted - a flat node_modules without symlinks is created. Same as the node_modules created by npm or Yarn Classic. При використанні цього параметра для підйому використовується одна з бібліотек Yarn. Законні причини для використання цього налаштування:
  1. Ваші інструменти погано працюють із символічними посиланнями. A React Native project will most probably only work if you use a hoisted node_modules.
  2. Ваш проєкт буде розгорнуто на безсерверний хостинг. Деякі безсерверні провайдери (наприклад, AWS Lambda) не підтримують symlinks. Альтернативним розвʼязання цієї проблеми є пакування програми перед розгортанням.
  3. If you want to publish your package with "bundledDependencies".
  4. If you are running Node.js with the --preserve-symlinks flag.
• pnp - no node_modules. Plug'n'Play is an innovative strategy for Node that is used by Yarn Berry. It is recommended to also set symlink setting to false when using pnp as your linker.

symlink

• Default: true
• Type: Boolean

When symlink is set to false, pnpm creates a virtual store directory without any symlinks. It is a useful setting together with nodeLinker=pnp.

enableModulesDir

• Default: true
• Type: Boolean

When false, pnpm will not write any files to the modules directory (node_modules). Це корисно, коли теку модулів змонтовано з файловою системою у просторі користувача (FUSE). There is an experimental CLI that allows you to mount a modules directory with FUSE: @pnpm/mount-modules.

virtualStoreDir

• Default: node_modules/.pnpm
• Types: path

Тека з посиланнями на сховище. Всі прямі та непрямі залежності проєкту повʼязані з цією текою.

Це корисний параметр, який може усунути проблеми з довгими шляхами у Windows. If you have some dependencies with very long paths, you can select a virtual store in the root of your drive (for instance C:\my-project-store).

Or you can set the virtual store to .pnpm and add it to .gitignore. Це зробить трасування стеку чистішим, оскільки шляхи до залежностей будуть на одну теку вище.

NOTE: the virtual store cannot be shared between several projects. Кожен проєкт повинен мати власне віртуальне сховище (за винятком робочих просторів, де корінь є спільним).

virtualStoreDirMaxLength

• Стандартно:
  • У Linux/macOS: 120
  • У Windows: 60
• Types: number

Sets the maximum allowed length of directory names inside the virtual store directory (node_modules/.pnpm). Ви можете встановити менше значення, якщо у вас виникають проблеми з довгими шляхами у Windows.

packageImportMethod

• Default: auto
• Type: auto, hardlink, copy, clone, clone-or-copy

Controls the way packages are imported from the store (if you want to disable symlinks inside node_modules, then you need to change the nodeLinker setting, not this one).

• auto - try to clone packages from the store. Якщо клонування не підтримується, встановіть жорстке посилання на пакунки зі сховища. Якщо ані клонування, ані звʼязування неможливі, поверніться до копіювання
• hardlink - hard link packages from the store
• clone-or-copy - try to clone packages from the store. Якщо клонування не підтримується, поверніться до копіювання
• copy - copy packages from the store
• clone - clone (AKA copy-on-write or reference link) packages from the store

Клонування — найкращий спосіб запису пакунків у node_modules. Це найшвидший і найбезпечніший спосіб. Коли використовується клонування, ви можете редагувати файли у ваших node_modules, і вони не будуть змінені у центральному сховищі з адресованим вмістом.

На жаль, не всі файлові системи підтримують клонування. Ми рекомендуємо використовувати файлову систему з копіюванням при записі (CoW) (наприклад, Btrfs замість Ext4 в Linux) для найкращого досвіду роботи з pnpm.

modulesCacheMaxAge

• Default: 10080 (7 days in minutes)
• Type: number

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

dlxCacheMaxAge

• Default: 1440 (1 day in minutes)
• Type: number

Час у хвилинах, через який закінчується кеш dlx. Після виконання команди dlx pnpm зберігає кеш, який пропускає крок встановлення для наступних викликів тієї самої команди dlx.

Налаштування сховища

storeDir

• Стандартно:
  • If the $PNPM_HOME env variable is set, then $PNPM_HOME/store
  • If the $XDG_DATA_HOME env variable is set, then $XDG_DATA_HOME/pnpm/store
  • On Windows: ~/AppData/Local/pnpm/store
  • On macOS: ~/Library/pnpm/store
  • On Linux: ~/.local/share/pnpm/store
• Type: path

Місце, де зберігаються всі пакунки на диску.

Сховище завжди має бути на тому самому диску, на якому відбувається встановлення, тому на кожному диску буде одне сховище. Якщо на поточному диску є домашня тека, то сховище створюється всередині неї. Якщо на диску немає домашньої теки, то сховище створюється у корені файлової системи. For example, if installation is happening on a filesystem mounted at /mnt, then the store will be created at /mnt/.pnpm-store. Те ж саме стосується і систем Windows.

Можна встановити сховище з іншого диска, але у цьому випадку pnpm копіюватиме пакунки зі сховища, а не звʼязуватиме їх жорсткими посиланнями, оскільки жорсткі посилання можливі лише у тій самій файловій системі.

verifyStoreIntegrity

• Default: true
• Type: Boolean

By default, if a file in the store has been modified, the content of this file is checked before linking it to a project's node_modules. If verifyStoreIntegrity is set to false, files in the content-addressable store will not be checked during installation.

useRunningStoreServer

небезпека

Застаріла функція

• Default: false
• Type: Boolean

Дозволяє встановлення лише з сервером сховища. Якщо жоден сервер сховища не запущено, інсталяція завершиться невдало.

strictStorePkgContentCheck

• Default: true
• Type: Boolean

Деякі реєстри дозволяють публікувати один і той самий контент з різними назвами пакунків та/або версіями. Це порушує перевірку дійсності пакунків у сховищі. To avoid errors when verifying the names and versions of such packages in the store, you may set the strictStorePkgContentCheck setting to false.

Параметри Lockfile

lockfile

• Default: true
• Type: Boolean

When set to false, pnpm won't read or generate a pnpm-lock.yaml file.

preferFrozenLockfile

• Default: true
• Type: Boolean

When set to true and the available pnpm-lock.yaml satisfies the package.json dependencies directive, a headless installation is performed. Встановлення headless пропускає визначення всіх залежностей, оскільки йому не потрібно змінювати файл блокування.

lockfileIncludeTarballUrl

• Default: false
• Type: Boolean

Add the full URL to the package's tarball to every entry in pnpm-lock.yaml.

gitBranchLockfile

• Default: false
• Type: Boolean

When set to true, the generated lockfile name after installation will be named based on the current branch name to completely avoid merge conflicts. For example, if the current branch name is feature-foo, the corresponding lockfile name will be pnpm-lock.feature-foo.yaml instead of pnpm-lock.yaml. It is typically used in conjunction with the command line argument --merge-git-branch-lockfiles or by setting mergeGitBranchLockfilesBranchPattern in the pnpm-workspace.yaml file.

mergeGitBranchLockfilesBranchPattern

• Default: null
• Type: Array or null

This configuration matches the current branch name to determine whether to merge all git branch lockfile files. By default, you need to manually pass the --merge-git-branch-lockfiles command line parameter. This configuration allows this process to be automatically completed.

Наприклад:

mergeGitBranchLockfilesBranchPattern:
- main
- release*

You may also exclude patterns using !.

peersSuffixMaxLength

• Default: 1000
• Type: number

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

Registry & Authentication Settings

registry

• Default: https://registry.npmjs.org/
• Type: url

The base URL of the npm package registry (trailing slash included).

<scope>:registry

The npm registry that should be used for packages of the specified scope. For example, setting @babel:registry=https://example.com/packages/npm/ will enforce that when you use pnpm add @babel/core, or any @babel scoped package, the package will be fetched from https://example.com/packages/npm instead of the default registry.

<URL>:_authToken

Define the authentication bearer token to use when accessing the specified registry. Наприклад:

//registry.npmjs.org/:_authToken=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 

You may also use an environment variable. Наприклад:

//registry.npmjs.org/:_authToken=${NPM_TOKEN}

Or you may just use an environment variable directly, without changing .npmrc at all:

npm_config_//registry.npmjs.org/:_authToken=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 

<URL>:tokenHelper

A token helper is an executable which outputs an auth token. This can be used in situations where the authToken is not a constant value but is something that refreshes regularly, where a script or other tool can use an existing refresh token to obtain a new access token.

The configuration for the path to the helper must be an absolute path, with no arguments. In order to be secure, it is only permitted to set this value in the user .npmrc. Otherwise a project could place a value in a project's local .npmrc and run arbitrary executables.

Setting a token helper for the default registry:

tokenHelper=/home/ivan/token-generator

Setting a token helper for the specified registry:

//registry.corp.com:tokenHelper=/home/ivan/token-generator

Налаштування запиту

ca

• Default: The npm CA certificate
• Type: String, Array or null

Сертифікат підпису центру сертифікації, якому довіряють для SSL-зʼєднань з реєстром. Значення повинні бути у форматі PEM (також відомий як «Base-64 кодований X.509 (.CER)»). Наприклад:

ca="-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----"

Встановіть значення null, щоб дозволити довіряти лише відомим реєстраторам, або певному сертифікату ЦС, щоб довіряти лише цьому конкретному центру сертифікації підписів.

Можна довіряти декільком центрам сертифікації, вказавши масив сертифікатів:

ca[]="..."
ca[]="..."

See also the strict-ssl config.

cafile

• Default: null
• Type: path

Шлях до файлу, що містить один або декілька сертифікатів підпису центру сертифікації. Similar to the ca setting, but allows for multiple CAs, as well as for the CA information to be stored in a file instead of being specified via CLI.

<URL>:cafile

Define the path to a Certificate Authority file to use when accessing the specified registry. Наприклад:

//registry.npmjs.org/:cafile=ca-cert.pem

cert

• Default: null
• Type: String

Клієнтський сертифікат, який потрібно передати при доступі до реєстру. Значення повинні бути у форматі PEM (також відомий як «Base-64 кодований X.509 (.CER)»). Наприклад:

cert="-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----"

It is not the path to a certificate file.

<URL>:certfile

Define the path to a certificate file to use when accessing the specified registry. Наприклад:

//registry.npmjs.org/:certfile=server-cert.pem

key

• Default: null
• Type: String

Ключ клієнта, який потрібно передати при доступі до реєстру. Значення повинні бути у форматі PEM (також відомий як «Base-64 кодований X.509 (.CER)»). Наприклад:

key="-----BEGIN PRIVATE KEY-----\nXXXX\nXXXX\n-----END PRIVATE KEY-----"

It is not the path to a key file (and there is no keyfile option).

Цей параметр містить конфіденційну інформацію. Don't write it to a local .npmrc file committed to the repository.

<URL>:keyfile

Define the path to a client key file to use when accessing the specified registry. Наприклад:

//registry.npmjs.org/:keyfile=server-key.pem

gitShallowHosts

• Default: ['github.com', 'gist.github.com', 'gitlab.com', 'bitbucket.com', 'bitbucket.org']
• Type: string[]

Під час отримання залежностей, які є Git-репозиторіями, якщо хост вказано у цьому параметрі, pnpm використовуватиме неглибоке клонування, щоб отримати лише потрібний комміт, а не всю історію.

https-proxy

• Default: null
• Type: url

Проксі-сервер для вихідних HTTPS-запитів. If the HTTPS_PROXY, https_proxy, HTTP_PROXY or http_proxy environment variables are set, their values will be used instead.

If your proxy URL contains a username and password, make sure to URL-encode them. Наприклад:

https-proxy=https://use%21r:pas%2As@my.proxy:1234/foo

Do not encode the colon (:) between the username and password.

http-proxy

proxy

• Default: null
• Type: url

Проксі для вихідних http-запитів. Якщо встановлено змінні оточення HTTP_PROXY або http_proxy, налаштування проксі будуть враховані базовою бібліотекою запитів.

local-address

• Default: undefined
• Type: IP Address

IP-адреса локального інтерфейсу для підключення до реєстру npm.

maxsockets

• Default: networkConcurrency x 3
• Type: Number

Максимальна кількість зʼєднань, які можна використовувати для одного джерела (комбінація протокол/хост/порт).

noproxy

• Default: null
• Type: String

Розділений комами рядок розширень доменів, для яких не слід використовувати проксі-сервер.

strict-ssl

• Default: true
• Type: Boolean

Чи потрібно робити перевірку SSL-ключів при запитах до реєстру через HTTPS.

See also the ca option.

networkConcurrency

• Default: 16
• Type: Number

Контролює максимальну кількість запитів HTTP(S) для одночасної обробки.

fetchRetries

• Default: 2
• Type: Number

Скільки разів повторити спробу, якщо pnpm не вдається отримати дані з реєстру.

fetchRetryFactor

• Default: 10
• Type: Number

Експоненціальний коефіцієнт для повторної спроби.

fetchRetryMintimeout

• Default: 10000 (10 seconds)
• Type: Number

Мінімальний (базовий) тайм-аут для повторних запитів.

fetchRetryMaxtimeout

• Default: 60000 (1 minute)
• Type: Number

Максимальний таймаут очікування, щоб гарантувати, що фактор повторних спроб не робить запити занадто довгими.

fetchTimeout

• Default: 60000 (1 minute)
• Type: Number

Максимальний час очікування виконання HTTP-запитів.

Параметри прямих залежностей

autoInstallPeers

• Default: true
• Type: Boolean

When true, any missing non-optional peer dependencies are automatically installed.

Конфлікт версій

Якщо існують суперечливі вимоги до версій для прямої залежності з різних пакунків, pnpm не встановлюватиме автоматично жодну з версій суперечливої прямої залежності. Натомість виводиться попередження. For example, if one dependency requires react@^16.0.0 and another requires react@^17.0.0, these requirements conflict, and no automatic installation will occur.

Розвʼязання конфліктів

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

dedupePeerDependents

• Default: true
• Type: Boolean

When this setting is set to true, packages with peer dependencies will be deduplicated after peers resolution.

For instance, let's say we have a workspace with two projects and both of them have webpack in their dependencies. webpack has esbuild in its optional peer dependencies, and one of the projects has esbuild in its dependencies. In this case, pnpm will link two instances of webpack to the node_modules/.pnpm directory: one with esbuild and another one without it:

node_modules
  .pnpm
    webpack@1.0.0_esbuild@1.0.0
    webpack@1.0.0
project1
  node_modules
    webpack -> ../../node_modules/.pnpm/webpack@1.0.0/node_modules/webpack
project2
  node_modules
    webpack -> ../../node_modules/.pnpm/webpack@1.0.0_esbuild@1.0.0/node_modules/webpack
    esbuild

This makes sense because webpack is used in two projects, and one of the projects doesn't have esbuild, so the two projects cannot share the same instance of webpack. However, this is not what most developers expect, especially since in a hoisted node_modules, there would only be one instance of webpack. Therefore, you may now use the dedupePeerDependents setting to deduplicate webpack when it has no conflicting peer dependencies (explanation at the end). In this case, if we set dedupePeerDependents to true, both projects will use the same webpack instance, which is the one that has esbuild resolved:

node_modules
  .pnpm
    webpack@1.0.0_esbuild@1.0.0
project1
  node_modules
    webpack -> ../../node_modules/.pnpm/webpack@1.0.0_esbuild@1.0.0/node_modules/webpack
project2
  node_modules
    webpack -> ../../node_modules/.pnpm/webpack@1.0.0_esbuild@1.0.0/node_modules/webpack
    esbuild

What are conflicting peer dependencies? By conflicting peer dependencies we mean a scenario like the following one:

node_modules
  .pnpm
    webpack@1.0.0_react@16.0.0_esbuild@1.0.0
    webpack@1.0.0_react@17.0.0
project1
  node_modules
    webpack -> ../../node_modules/.pnpm/webpack@1.0.0/node_modules/webpack
    react (v17)
project2
  node_modules
    webpack -> ../../node_modules/.pnpm/webpack@1.0.0_esbuild@1.0.0/node_modules/webpack
    esbuild
    react (v16)

In this case, we cannot dedupe webpack as webpack has react in its peer dependencies and react is resolved from two different versions in the context of the two projects.

strictPeerDependencies

• Default: false
• Type: Boolean

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

resolvePeersFromWorkspaceRoot

• Default: true
• Type: Boolean

Якщо увімкнено, залежності кореневого проєкту робочої області використовуються для розвʼязання прямих залежностей будь-яких проєктів у робочій області. Це корисна функція, оскільки ви можете встановлювати прямі залежності лише у корені робочого простору, і ви можете бути впевнені, що всі проєкти у робочому просторі використовують однакові версії прямих залежностей.

peerDependencyRules

peerDependencyRules.ignoreMissing

pnpm will not print warnings about missing peer dependencies from this list.

For instance, with the following configuration, pnpm will not print warnings if a dependency needs react but react is not installed:

peerDependencyRules:
  ignoreMissing:
  - react

Також можна використовувати шаблони назв пакунків:

peerDependencyRules:
  ignoreMissing:
  - "@babel/*"
  - "@eslint/*"

peerDependencyRules.allowedVersions

Unmet peer dependency warnings will not be printed for peer dependencies of the specified range.

For instance, if you have some dependencies that need react@16 but you know that they work fine with react@17, then you may use the following configuration:

peerDependencyRules:
  allowedVersions:
    react: "17"

This will tell pnpm that any dependency that has react in its peer dependencies should allow react v17 to be installed.

It is also possible to suppress the warnings only for peer dependencies of specific packages. For instance, with the following configuration react v17 will be only allowed when it is in the peer dependencies of the button v2 package or in the dependencies of any card package:

peerDependencyRules:
  allowedVersions:
    "button@2>react": "17",
    "card>react": "17"

peerDependencyRules.allowAny

allowAny is an array of package name patterns, any peer dependency matching the pattern will be resolved from any version, regardless of the range specified in peerDependencies. Наприклад:

peerDependencyRules:
  allowAny:
  - "@babel/*"
  - "eslint"

The above setting will mute any warnings about peer dependency version mismatches related to @babel/ packages or eslint.

Параметри CLI

[no-]color

• Default: auto
• Type: auto, always, never

Керує кольорами у виводі.

• auto - output uses colors when the standard output is a terminal or TTY.
• always - ignore the difference between terminals and pipes. You’ll rarely want this; in most scenarios, if you want color codes in your redirected output, you can instead pass a --color flag to the pnpm command to force it to use color codes. Стандартні налаштування майже завжди відповідають вашим потребам.
• never - turns off colors. This is the setting used by --no-color.

loglevel

• Default: info
• Type: debug, info, warn, error

Будуть показані всі журнали вказаного рівня або вище. You can instead pass --silent to turn off all output logs.

useBetaCli

• Default: false
• Type: Boolean

Експериментальна опція, яка дозволяє використовувати бета-функції CLI. Це означає, що ви можете отримати деякі зміни у функціоналі CLI, які є порушеннями або потенційними помилками.

recursiveInstall

• Default: true
• Type: Boolean

If this is enabled, the primary behaviour of pnpm install becomes that of pnpm install -r, meaning the install is performed on all workspace or subdirectory packages.

Else, pnpm install will exclusively build the package in the current directory.

engineStrict

• Default: false
• Type: Boolean

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

Regardless of this configuration, installation will always fail if a project (not a dependency) specifies an incompatible version in its engines field.

npmPath

• Type: path

Розташування бінарного файлу npm, який pnpm використовує для деяких дій, таких як публікація.

packageManagerStrict

• Default: true
• Type: Boolean

If this setting is disabled, pnpm will not fail if a different package manager is specified in the packageManager field of package.json. When enabled, only the package name is checked (since pnpm v9.2.0), so you can still run any version of pnpm regardless of the version specified in the packageManager field.

Alternatively, you can disable this setting by setting the COREPACK_ENABLE_STRICT environment variable to 0.

packageManagerStrictVersion

• Default: false
• Type: Boolean

When enabled, pnpm will fail if its version doesn't exactly match the version specified in the packageManager field of package.json.

managePackageManagerVersions

• Default: true
• Type: Boolean

When enabled, pnpm will automatically download and run the version of pnpm specified in the packageManager field of package.json. Це те саме поле, що використовується Corepack. Приклад:

{
  "packageManager": "pnpm@9.3.0"
}

Параметри збирання

ignoreScripts

• Default: false
• Type: Boolean

Do not execute any scripts defined in the project package.json and its dependencies.

нотатка

This flag does not prevent the execution of .pnpmfile.cjs

ignoreDepScripts

• Default: false
• Type: Boolean

Не виконувати жодних скриптів встановлених пакунків. Скрипти проєктів виконуються.

нотатка

Since v10, pnpm doesn't run the lifecycle scripts of dependencies unless they are listed in onlyBuiltDependencies.

childConcurrency

• Default: 5
• Type: Number

Максимальна кількість дочірніх процесів, які можна одночасно виділити для збірки node_modules.

sideEffectsCache

• Default: true
• Type: Boolean

Використовувати та кешувати результати хуків (пре/пост)встановлення.

sideEffectsCacheReadonly

• Default: false
• Type: Boolean

Використовувати кеш побічних ефектів лише за наявності, не створювати його для нових пакунків.

unsafePerm

• Default: false IF running as root, ELSE true
• Type: Boolean

Встановіть значення true, щоб увімкнути перемикання UID/GID під час запуску скриптів пакунків. Якщо явно вказати значення false, то встановлення від імені не root-користувача не вдасться.

nodeOptions

• Default: NULL
• Type: String

Options to pass through to Node.js via the NODE_OPTIONS environment variable. This does not impact how pnpm itself is executed but it does impact how lifecycle scripts are called.

verifyDepsBeforeRun

• Default: false
• Тип: install, warn, error, prompt, false

Цей параметр дозволяє перевіряти стан залежностей перед запуском сценаріїв. Перевірка виконується для команд pnpm run і pnpm exec. Підтримуються наступні значення:

• install — Автоматично запускає встановлення, якщо node_modules не оновлено.
• warn — Виводить попередження, якщо вміст node_modules не є актуальним.
• prompt — Запитує у користувача дозвіл на запуск встановлення, якщо node_modules не оновлено.
• error — Викликає помилку, якщо node_modules не є актуальним.
• false — Вимикає перевірку залежностей.

strictDepBuilds

Додано у: v10.3.0

• Default: false
• Type: Boolean

When strictDepBuilds is enabled, the installation will exit with a non-zero exit code if any dependencies have unreviewed build scripts (aka postinstall scripts).

neverBuiltDependencies

This field allows to ignore the builds of specific dependencies. The "preinstall", "install", and "postinstall" scripts of the listed packages will not be executed during installation.

An example of the neverBuiltDependencies field:

neverBuiltDependencies:
- fsevents
- level

onlyBuiltDependencies

A list of package names that are allowed to be executed during installation. Лише пакунки, перелічені у цьому масиві, зможуть запускати сценарії встановлення. Якщо onlyBuiltDependenciesFile і neverBuiltDependencies не встановлено, цей параметр конфігурації стандартно блокуватиме всі сценарії встановлення.

Приклад:

onlyBuiltDependencies:
- fsevents

onlyBuiltDependenciesFile

Цей параметр конфігурації дозволяє користувачам вказати JSON-файл зі списком лише тих пакунків, для яких дозволено запускати сценарії встановлення під час процесу встановлення pnpm. За допомогою цього ви можете підвищити безпеку або гарантувати, що під час встановлення скрипти виконуватимуться лише у певних залежностях.

Приклад:

configDependencies:
  "@my-org/policy": 1.0.0+sha512-30iZtAPgz+LTIYoeivqYo853f02jBYSd5uGnGpkFV0M3xOt9aN73erkgYAmZU43x4VfqcnLxW9Kpg3R5LC4YYw==
onlyBuiltDependenciesFile: node_modules/.pnpm-config/@my-org/policy/onlyBuiltDependencies.json

Сам JSON-файл повинен містити масив імен пакунків:

node_modules/@my-org/policy/onlyBuiltDependencies.json

[
  "fsevents"
]

ignoredBuiltDependencies

Додано у: v10.1.0

Список назв пакунків, які не слід збирати під час встановлення.

Приклад:

ignoredBuiltDependencies:
- fsevents

Параметри Node.js

useNodeVersion

• Default: undefined
• Type: semver

Вказує, яку саме версію Node.js слід використовувати для виконання проєкту. pnpm will automatically install the specified version of Node.js and use it for running pnpm run commands or the pnpm node command.

This may be used instead of .nvmrc and nvm. Instead of the following .nvmrc file:

16.16.0

Use this pnpm-workspace.yaml file:

useNodeVersion: 16.16.0

This setting works only in a pnpm-workspace.yaml file that is in the root of your workspace. If you need to specify a custom Node.js for a project in the workspace, use the executionEnv.nodeVersion field of package.json instead.

nodeVersion

• Default: the value returned by node -v, without the v prefix
• Type: semver

The Node.js version to use when checking a package's engines setting.

If you want to prevent contributors of your project from adding new incompatible dependencies, use nodeVersion and engineStrict in a pnpm-workspace.yaml file at the root of the project:

nodeVersion: 12.22.0
engineStrict: true

Таким чином, навіть якщо хтось використовує Node.js v16, він не зможе встановити нову залежність, яка не підтримує Node.js v12.22.0.

node-mirror

• Default: https://nodejs.org/download/<releaseDir>/
• Type: URL

Задає базову URL-адресу для завантаження Node.js. The <releaseDir> portion of this setting can be any directory from https://nodejs.org/download: release, rc, nightly, v8-canary, etc.

Ось як можна налаштувати pnpm для завантаження Node.js з дзеркала Node.js в Китаї:

node-mirror:release=https://npmmirror.com/mirrors/node/
node-mirror:rc=https://npmmirror.com/mirrors/node-rc/
node-mirror:nightly=https://npmmirror.com/mirrors/node-nightly/

executionEnv.nodeVersion

Вказує, яку саме версію Node.js слід використовувати для виконання проєкту. pnpm will automatically install the specified version of Node.js and use it for running pnpm run commands or the pnpm node command.

Наприклад:

executionEnv:
  nodeVersion: 16.16.0

Налаштування робочого простору

linkWorkspacePackages

• Default: false
• Type: true, false, deep

If this is enabled, locally available packages are linked to node_modules instead of being downloaded from the registry. This is very convenient in a monorepo. If you need local packages to also be linked to subdependencies, you can use the deep setting.

Else, packages are downloaded and installed from the registry. However, workspace packages can still be linked by using the workspace: range protocol.

Packages are only linked if their versions satisfy the dependency ranges.

injectWorkspacePackages

• Default: false
• Type: Boolean

Вмикає жорстке звʼязування всіх локальних залежностей робочого простору замість їхнього звʼязування у вигляді символічних посилань. Крім того, цього можна досягти за допомогою dependenciesMeta[].injected, що дозволяє вибірково вмикати жорстке зв’язування для певних залежностей.

syncInjectedDepsAfterScripts

Додано у: v10.5.0

• Default: undefined
• Тип: String[]

Інʼєкції залежності робочого простору — це колекції жорстких посилань, які не додають і не видаляють файли при зміні їхніх джерел. Це спричиняє проблеми у пакунках, які потрібно зібрати (наприклад, у проєктах на TypeScript).

Цей параметр являє собою список назв скриптів. Коли будь-який з цих скриптів виконується у пакунку робочої області, інʼєкції залежностей всередині node_modules також буде синхронізовано.

preferWorkspacePackages

• Default: false
• Type: Boolean

If this is enabled, local packages from the workspace are preferred over packages from the registry, even if there is a newer version of the package in the registry.

This setting is only useful if the workspace doesn't use saveWorkspaceProtocol.

sharedWorkspaceLockfile

• Default: true
• Type: Boolean

If this is enabled, pnpm creates a single pnpm-lock.yaml file in the root of the workspace. This also means that all dependencies of workspace packages will be in a single node_modules (and get symlinked to their package node_modules folder for Node's module resolution).

Advantages of this option:

• кожна залежність є одиночною
• швидші установки в монорепо
• менше змін у перевірках коду, оскільки всі вони містяться в одному файлі

нотатка

Even though all the dependencies will be hard linked into the root node_modules, packages will have access only to those dependencies that are declared in their package.json, so pnpm's strictness is preserved. This is a result of the aforementioned symbolic linking.

saveWorkspaceProtocol

• Default: rolling
• Type: true, false, rolling

This setting controls how dependencies that are linked from the workspace are added to package.json.

If foo@1.0.0 is in the workspace and you run pnpm add foo in another project of the workspace, below is how foo will be added to the dependencies field. The savePrefix setting also influences how the spec is created.

saveWorkspaceProtocol	savePrefix	spec
false	''	1.0.0
false	'~'	~1.0.0
false	'^'	^1.0.0
true	''	workspace:1.0.0
true	'~'	workspace:~1.0.0
true	'^'	workspace:^1.0.0
rolling	''	workspace:*
rolling	'~'	workspace:~
rolling	'^'	workspace:^

includeWorkspaceRoot

• Default: false
• Type: Boolean

При рекурсивному виконанні команд у робочій області, виконуйте їх також у кореневому проєкті робочої області.

ignoreWorkspaceCycles

• Default: false
• Type: Boolean

When set to true, no workspace cycle warnings will be printed.

disallowWorkspaceCycles

• Default: false
• Type: Boolean

When set to true, installation will fail if the workspace has cycles.

Налаштування розгортання

forceLegacyDeploy

• Default: false
• Type: Boolean

Стандартно, pnpm deploy спробує створити спеціальний файл блокування зі спільного файлу блокування для розгортання. Якщо цей параметр встановлено у значення true, буде використано успадковану поведінку deploy.

Patching Dependencies

patchedDependencies

This field is added/updated automatically when you run pnpm patch-commit. It defines patches for dependencies using a dictionary where:

• Keys: Package names with an exact version, a version range, or just the name.
• Values: Relative paths to patch files.

Приклад:

patchedDependencies:
  express@4.18.1: patches/express@4.18.1.patch

Dependencies can be patched by version range. The priority order is:

1. Exact versions (highest priority)
2. Version ranges
3. Name-only patches (applies to all versions unless overridden)

A special case: the version range * behaves like a name-only patch but does not ignore patch failures.

Exampe:

patchedDependencies:
  foo: patches/foo-1.patch
  foo@^2.0.0: patches/foo-2.patch
  foo@2.1.0: patches/foo-3.patch

• patches/foo-3.patch is applied to foo@2.1.0.
• patches/foo-2.patch applies to all foo versions matching ^2.0.0, except 2.1.0.
• patches/foo-1.patch applies to all other foo versions.

Avoid overlapping version ranges. If you need to specialize a sub-range, explicitly exclude it from the broader range.

Приклад:

patchedDependencies:
  # Specialized sub-range
  "foo@2.2.0-2.8.0": patches/foo.2.2.0-2.8.0.patch
  # General patch, excluding the sub-range above
  "foo@>=2.0.0 <2.2.0 || >2.8.0": patches/foo.gte2.patch

In most cases, defining an exact version is enough to override a broader range.

allowUnusedPatches

Added in: v10.7.0 (Previously named allowNonAppliedPatches)

• Default: false
• Type: Boolean

When true, installation won't fail if some of the patches from the patchedDependencies field were not applied.

patchedDependencies:
  express@4.18.1: patches/express@4.18.1.patch
allowUnusedPatches: true

ignorePatchFailures

Added in: v10.7.0

• Default: undefined
• Type: Boolean, undefined

Controls how patch failures are handled.

Behaviour:

• undefined (default):
  • Errors out when a patch with an exact version or version range fails.
  • Ignores failures from name-only patches.
• false: Errors out for any patch failure.
• true: Prints a warning instead of failing when any patch cannot be applied.

Audit Settings

auditConfig

auditConfig.ignoreCves

A list of CVE IDs that will be ignored by the pnpm audit command.

auditConfig:
  ignoreCves:
    CVE-2022-36313

auditConfig.ignoreGhsas

A list of GHSA Codes that will be ignored by the pnpm audit command.

auditConfig:
  ignoreGhsas:
    GHSA-42xw-2xvc-qx8m
    GHSA-4w2v-q235-vp99
    GHSA-cph5-m8f7-6c5x
    GHSA-vh95-rmgr-6w4m

Інші налаштування

savePrefix

• Default: '^'
• Type: '^', '~', ''

Configure how versions of packages installed to a package.json file get prefixed.

For example, if a package has version 1.2.3, by default its version is set to ^1.2.3 which allows minor upgrades for that package, but after pnpm config set save-prefix='~' it would be set to ~1.2.3 which only allows patch upgrades.

Цей параметр ігнорується, якщо доданий пакунок має вказаний діапазон. For instance, pnpm add foo@2 will set the version of foo in package.json to 2, regardless of the value of savePrefix.

tag

• Default: latest
• Type: String

If you pnpm add a package and you don't provide a specific version, then it will install the package at the version registered under the tag from this setting.

This also sets the tag that is added to the package@version specified by the pnpm tag command if no explicit tag is given.

globalDir

• Стандартно:
  • If the $XDG_DATA_HOME env variable is set, then $XDG_DATA_HOME/pnpm/global
  • On Windows: ~/AppData/Local/pnpm/global
  • On macOS: ~/Library/pnpm/global
  • On Linux: ~/.local/share/pnpm/global
• Type: path

Вкажіть власну теку для зберігання глобальних пакунків.

globalBinDir

• Стандартно:
  • If the $XDG_DATA_HOME env variable is set, then $XDG_DATA_HOME/pnpm
  • On Windows: ~/AppData/Local/pnpm
  • On macOS: ~/Library/pnpm
  • On Linux: ~/.local/share/pnpm
• Type: path

Дозволяє задати цільову теку для bin-файлів глобально встановлених пакунків.

stateDir

• Стандартно:
  • If the $XDG_STATE_HOME env variable is set, then $XDG_STATE_HOME/pnpm
  • On Windows: ~/AppData/Local/pnpm-state
  • On macOS: ~/.pnpm-state
  • On Linux: ~/.local/state/pnpm
• Type: path

The directory where pnpm creates the pnpm-state.json file that is currently used only by the update checker.

cacheDir

• Стандартно:
  • If the $XDG_CACHE_HOME env variable is set, then $XDG_CACHE_HOME/pnpm
  • On Windows: ~/AppData/Local/pnpm-cache
  • On macOS: ~/Library/Caches/pnpm
  • On Linux: ~/.cache/pnpm
• Type: path

Розташування кешу (метадані пакунків та dlx).

useStderr

• Default: false
• Type: Boolean

Якщо значення true, весь вивід записується у stderr.

updateNotifier

• Default: true
• Type: Boolean

Set to false to suppress the update notification when using an older version of pnpm than the latest.

preferSymlinkedExecutables

• Default: true, when node-linker is set to hoisted and the system is POSIX
• Type: Boolean

Create symlinks to executables in node_modules/.bin instead of command shims. Цей параметр ігнорується у Windows, де працюють лише командні shims.

ignoreCompatibilityDb

• Default: false
• Type: Boolean

Під час встановлення автоматично виправляються залежності деяких пакунків. If you want to disable this, set this config to false.

The patches are applied from Yarn's @yarnpkg/extensions package.

resolutionMode

• Default: highest (was lowest-direct from v8.0.0 to v8.6.12)
• Type: highest, time-based, lowest-direct

When resolutionMode is set to time-based, dependencies will be resolved the following way:

1. Прямі залежності будуть вирішені до найнижчих версій. So if there is foo@^1.1.0 in the dependencies, then 1.1.0 will be installed.
2. Підзалежності будуть врегульовані, починаючи з версій, які були опубліковані до того, як була опублікована остання пряма залежність.

У цьому режимі встановлення з "теплим" кеш відбувається швидше. Це також зменшує ймовірність перехоплення підзалежностей, оскільки підзалежності будуть оновлюватися лише тоді, коли оновлюються прямі залежності.

This resolution mode works only with npm's full metadata. Тому в деяких сценаріях це відбувається повільніше. However, if you use Verdaccio v5.15.1 or newer, you may set the registrySupportsTimeField setting to true, and it will be really fast.

When resolutionMode is set to lowest-direct, direct dependencies will be resolved to their lowest versions.

registrySupportsTimeField

• Default: false
• Type: Boolean

Set this to true if the registry that you are using returns the "time" field in the abbreviated metadata. As of now, only Verdaccio from v5.15.1 supports this.

extendNodePath

• Default: true
• Type: Boolean

When false, the NODE_PATH environment variable is not set in the command shims.

deployAllFiles

• Default: false
• Type: Boolean

When deploying a package or installing a local package, all files of the package are copied. By default, if the package has a "files" field in the package.json, then only the listed files and directories are copied.

dedupeDirectDeps

• Default: false
• Type: Boolean

When set to true, dependencies that are already symlinked to the root node_modules directory of the workspace will not be symlinked to subproject node_modules directories.

dedupeInjectedDeps

• Default: true
• Type: Boolean

When this setting is enabled, dependencies that are injected will be symlinked from the workspace whenever possible. If the dependent project and the injected dependency reference the same peer dependencies, then it is not necessary to physically copy the injected dependency into the dependent's node_modules; a symlink is sufficient.

optimisticRepeatInstall

Додано у: v10.1.0

• Default: true
• Type: Boolean

Якщо увімкнено, буде виконано швидку перевірку перед початком інсталяції. Таким чином, повторне встановлення або встановлення в проєкті з усіма оновленнями стає набагато швидшим.

requiredScripts

Scripts listed in this array will be required in each project of the workspace. Otherwise, pnpm -r run <script name> will fail.

requiredScripts:
- build