Налаштування (pnpm-workspace.yaml)
pnpm отримує свою конфігурацію з командного рядка, змінних оточення, файлівpnpm-workspace.yaml
та .npmrc
.
Команду pnpm config
можна використовувати для читання та редагування вмісту файлів проєкту та файлів глобальної конфігурації.
Відповідні конфігураційні файли:
- Конфігураційний файл для кожного проєкту:
/path/to/my/project/pnpm-workspace.yaml
- Глобальний файл конфігурації:
~/.config/pnpm/rc
([INI-форматований] список параметрівkey = value
)
Параметри, пов’язані з авторизацією, обробляються системою конфігурації npm. Отже, pnpm config set registry=<value>
фактично збереже параметр у глобальний файл конфігурації npm.
Значення у файлах конфігурації можуть містити змінні env із використанням синтаксису ${NAME}
. Змінні env також можуть бути вказані зі стандартними значеннями. Використання ${NAME-fallback}
поверне fallback
, якщо NAME
не задано. ${NAME:-fallback}
поверне fallback
, якщо NAME
не задано або є порожнім рядком.
Розвʼязання залежностей
overrides
У цьому полі ви можете вказати pnpm перевизначити будь-яку залежність у графі залежностей. Це корисно для того, щоб змусити всі ваші пакунки використовувати одну версію залежності, перенести виправлення, замінити залежність форком або видалити невикористовувану залежність.
Зверніть увагу, що поле перевизначень можна встановити лише у корені проєкту.
Приклад поля overrides
:
overrides:
"foo": "^1.0.0"
"quux": "npm:@myorg/quux@^1.0.0"
"bar@^2.1.0": "3.0.0"
"qar@1>zoo": "2"
Ви можете вказати пакунок, до якого належить перевизначена залежність, відокремивши селектор пакунка від селектора залежності символом ">", наприклад, qar@1>zoo
перевизначить лише залежність zoo
пакунка qar@1
, а не будь-які інші залежності.
Перевизначення можна визначити як посилання на специфікацію прямої залежності.
Це досягається шляхом додавання до імені залежності префікса $
:
{
"dependencies": {
"foo": "^1.0.0"
}
}
overrides:
foo: "$foo"
Пакунок, на який посилаються, не обовʼязково повинен збігатися з пакунком, на який посилається перевизначений:
overrides:
bar: "$foo"
Якщо ви вважаєте, що використання певного пакунка не потребує однієї з його залежностей, ви можете використовувати -
, щоб вилучити її. Наприклад, якщо пакунок foo@1.0.0
потребує великого пакунка з назвою bar
для функції, яку ви не використовуєте, вилучення цього пакунка може скоротити час встановлення:
overrides:
"foo@1.0.0>bar": "-"
Ця можливість особливо корисна для optionalDependencies
, де більшість необовʼязкових пакунків можна безпечно пропустити.
packageExtensions
Поля packageExtensions
надають можливість розширити наявні визначення пакунків додатковою інформацією. Наприклад, якщо react-redux
повинен мати react-dom
у своїх peerDependencies
, але не має, можна виправити react-redux
за допомогою packageExtensions
:
packageExtensions:
react-redux:
peerDependencies:
react-dom: "*"
Ключами у packageExtensions
є назви пакунків або назви пакунків і діапазони semver, тому можна виправити лише деякі версії пакунків:
packageExtensions:
react-redux@1:
peerDependencies:
react-dom: "*"
Наступні поля можна розширити за допомогою packageExtensions
: dependencies
, optionalDependencies
, peerDependencies
і peerDependenciesMeta
.
Більший приклад:
packageExtensions:
express@1:
optionalDependencies:
typescript: "2"
fork-ts-checker-webpack-plugin:
dependencies:
"@babel/core": "1"
peerDependencies:
eslint: ">= 6"
peerDependenciesMeta:
eslint: {
optional: true
Разом з Yarn ми підтримуємо базу даних packageExtensions
для виправлення несправних пакунків в екосистемі.
Якщо ви використовуєте packageExtensions
, подумайте про те, щоб надіслати PR і внести ваше розширення до бази даних @yarnpkg/extensions
.
allowedDeprecatedVersions
Цей параметр дозволяє вимкнути попередження про застарілість певних пакунків.
Приклад:
allowedDeprecatedVersions:
express: "1"
request: "*"
У наведеній вище конфігурації pnpm не виводитиме попередження про застарілість для будь-якої версії request
і для v1 express
.
updateConfig
updateConfig.ignoreDependencies
Іноді ви не можете оновити залежність. Наприклад, остання версія залежності почала використовувати ESM, але ваш проєкт ще не в ESM. На жаль, такий пакунок завжди буде виведено командою pnpm outdated
і оновлено при виконанні pnpm update --latest
. Втім, ви можете перелічити пакунки, які не потрібно оновлювати, у полі ignoreDependencies
:
updateConfig:
ignoreDependencies:
- load-json-file
Також підтримуються шаблони, тому ви можете ігнорувати будь-які пакунки з області видимості: @babel/*
.
supportedArchitectures
Ви можете вказати архітектури, для яких ви хочете встановити необовʼязкові залежності, навіть якщо вони не відповідають архітектурі системи, на якій виконується встановлення.
Наприклад, у наведеній нижче конфігурації вказано встановити необовʼязкові залежності для Windows x64:
supportedArchitectures:
os:
- win32
cpu:
- x64
Тоді як ця конфігурація встановить необовʼязкові залежності для Windows, macOS та архітектури системи, на якій наразі виконується встановлення. Вона включає артефакти як для x64, так і для arm64 процесорів:
supportedArchitectures:
os:
- win32
- darwin
- current
cpu:
- x64
- arm64
Крім того, supportedArchitectures
також підтримує вказівку libc
системи.
ignoredOptionalDependencies
Якщо необовʼязкова залежність має імʼя у цьому масиві, її буде пропущено. Наприклад:
ignoredOptionalDependencies:
- fsevents
- "@esbuild/*"
Налаштування підйому залежностей
hoist
- Стандартно: true
- Тип: Boolean
Коли true
, всі залежності підіймаються до node_modules/.pnpm/node_modules
. Це робить не перелічені залежності доступними для всіх пакунків всередині node_modules
.
hoistWorkspacePackages
- Стандартно: true
- Тип: Boolean
Коли true
, пакунки з робочих просторів буде звʼязано або з <workspace_root>/node_modules/.pnpm/node_modules
, або з <workspace_root>/node_modules
, залежно від інших параметрів підйому (hoistPattern
та publicHoistPattern
).
hoistPattern
- Стандартно: ['*']
- Тип: string[]
Вказує pnpm, які пакунки слід підняти до node_modules/.pnpm/node_modules
. Стандартно, всі пакунки буде піднято — однак, якщо ви знаєте, що лише деякі пакунки мають фантомні залежності, ви можете скористатися цим параметром, щоб підняти лише фантомні залежності (рекомендується).
Наприклад:
hoistPattern:
- "*eslint*"
- "*babel*"
Ви також можете заборонити підйом шаблонів за допомогою !
.
Наприклад:
hoistPattern:
- "*types*"
- "!@types/react"
publicHoistPattern
- Стандартно: []
- Тип: string[]
На відміну від hoistPattern
, який підіймає залежності до прихованої теки модулів у віртуальному сховищі, publicHoistPattern
підіймає залежності, що відповідають шаблону, до кореневої теки модулів. Підняття до кореневої теки модулів означає, що код застосунку матиме доступ до фантомних залежностей, навіть якщо вони неправильно змінять стратегію розвʼязання.
Цей параметр корисний при роботі з деякими недосконалими інструментами, що підключаються, які не обробляють залежно сті належним чином.
Наприклад:
publicHoistPattern:
- "*plugin*"
Зауваження: Встановлення shamefullyHoist
у true
аналогічно встановленню publicHoistPattern
у *
.
Ви також можете заборонити підйом шаблонів за допомогою !
.
Наприклад:
publicHoistPattern:
- "*types*"
- "!@types/react"
shamefullyHoist
- Стандартно: false
- Тип: Boolean
Стандартно pnpm створює напівсувору теку node_modules
, тобто залежності мають доступ до неоголошених залежностей, а модулі поза межами node_modules
— ні.
За такої схеми більшість пакунків в екосистемі працюють без проблем.
Однак, якщо деякі інструменти працюють лише тоді, коли підняті залежності знаходяться у корені node_modules
, ви можете встановити цей параметр у true
, щоб підняти їх для вас.
Параметри модулів
modulesDir
- Стандартно: node_modules
- Тип: path
Тека, до якої буде встановлено залежності (замість node_modules
).
nodeLinker
- Стандартно: isolated
- Тип: isolated, hoisted, pnp
Визначає, який компонувальник слід використовувати для встановлення па кунків Node.
- isolated — залежності компонуються з віртуального сховища за адресою
node_modules/.pnpm
. - hoisted — створюється плаский
node_modules
без символічних посилань. Так само як іnode_modules
, створені за допомогою npm або Yarn Classic. При використанні цього параметра для підйому використовується одна з бібліотек Yarn. Законні причини для використання цього налаштування:- Ваші інструменти погано працюють із символічними посиланнями. Проєкт на React Native, швидше за все, буде працювати тільки в тому випадку, якщо ви використовуєте піднятий
node_modules
. - Ваш проєкт буде розгорнуто на безсерверний хостинг. Деякі безсерверні провайдери (наприклад, AWS Lambda) не підтримують symlinks. Альтернативним розвʼязання цієї проблеми є пакування програми перед розгортанням.
- Якщо ви хочете опублікувати свій пакунок за допомогою
"bundledDependencies"
. - Якщо ви використовуєте Node.js із прапорцем --preserve-symlinks.
- Ваші інструменти погано працюють із символічними посиланнями. Проєкт на React Native, швидше за все, буде працювати тільки в тому випадку, якщо ви використовуєте піднятий
- pnp — без
node_modules
. Plug'n'Play — це інноваційна стратегія для Node, яка використовується Yarn Berry. Рекомендується також встановити параметрsymlink
у значенняfalse
, якщо ви використовуєтеpnp
як ваш компонувальник.
символічне посилання
- Стандартно: true
- Тип: Boolean
Коли symlink
встановлено у false
, pnpm створює віртуальну теку сховища без жодних символьних посилань. Це корисний параметр разом з nodeLinker=pnp
.
enableModulesDir
- Стандартно: true
- Тип: Boolean
Якщо false
, pnpm не записуватиме жодних файлів до теки модулів (node_modules
). Це корисно, коли теку модулів змонтовано з файловою системою у просторі користувача (FUSE). Існує експериментальна версія CLI, яка дозволяє змонтувати теку модулів за допомогою FUSE: @pnpm/mount-modules.
virtualStoreDir
- Стандартно: node_modules/.pnpm
- Тип: path
Тека з посиланнями на сховище. Всі прямі та непрямі залежності проєкту повʼязані з цією текою.
Це корисний параметр, який може усунути проблеми з довгими шляхами у Windows. Якщо у вас є залежності з дуже довгими шляхами, ви можете вибрати віртуальне сховище у корені диска (наприклад, C:\my-project-store
).
Або ви можете встановити віртуальне сховище у .pnpm
і додати його до .gitignore
. Це зробить трасування стеку чистішим, оскільки шляхи до залежностей будуть на одну теку вище.
ПРИМІТКА: віртуальне сховище не може бути спільним для декількох проєктів. Кожен проєкт повинен мати власне віртуальне сховище (за винятком робочих просторів, де корінь є спільним).
virtualStoreDirMaxLength
- Стандартно:
- У Linux/macOS: 120
- У Windows: 60
- Тип: number
Встановлює максимально допустиму довжину назв тек всередині теки віртуального сховища (node_modules/.pnpm
). Ви можете встановити менше значення, якщо у вас виникають проблеми з довгими шляхами у Windows.
packageImportMethod
- Стандартно: auto
- Тип: auto, hardlink, copy, clone, clone-or-copy
Керує способом імпорту пакунків зі сховища (якщо ви хочете вимкнути symlinks всередині node_modules
, то вам потрібно змінити параметр nodeLinker, а не цей).
- auto — спробувати клонувати пакунки зі сховища. Якщо клонування не підтримується, встановіть жорстке посилання на пакунки зі сховища. Якщо ані клонування, ані звʼязування неможливі, поверніться до копіювання
- hardlink — жорстке посилання на пакунки зі сховища
- clone-or-copy — спробувати клонувати пакунки зі сховища. Якщо клонування не підтримується, поверніться до копіювання
- copy — скопіювати пакунки зі сховища
- clone —клонувати (те ж що й copy-on-write або посилатись за посиланням) пакунки зі сховища
Клонування — найкращий спосіб запису пакунків у node_modules. Це найшвидший і найбезпечніший спосіб. Коли використовується клонування, ви можете редагувати файли у ваших node_modules, і вони не будуть змінені у центральному сховищі з адресованим вмістом.
На жаль, не всі файлові системи підтримують клонування. Ми рекомендуємо використовувати файлову систему з копіюванням при записі (CoW) (наприклад, Btrfs замість Ext4 в Linux) для найкращого досвіду роботи з pnpm.
modulesCacheMaxAge
- Стандартно: 10080 (7 днів в хвилинах)
- Тип: number
Час у хвилинах, через який слід видалити порожні пакунки з теки модулів. pnpm зберігає кеш пакунків у теці модулів. Це підвищує швидкість встановлення при перемиканні гілок або пониженню версій залежност ей.
dlxCacheMaxAge
- Стандартно: 1440 (1 день в хвилинах)
- Тип: number
Час у хвилинах, через який закінчується кеш dlx. Після виконання команди dlx pnpm зберігає кеш, який пропускає крок встановлення для наступних викликів тієї самої команди dlx.
enableGlobalVirtualStore
Додано у: v10.12.1
- Стандартно: false (завжди false в CI)
- Тип: Boolean
- Статус: Experimental
Якщо увімкнено, node_modules
містить лише символьні посилання на центральне віртуальне сховище, а не на node_modules/.pnpm
. Стандартно, це центральне сховище розташовано за адресою <store-path>/links
(використовуйте pnpm store path
, щоб знайти <store-path>
).
У центральному віртуальному сховищі кожен пакунок жорстко повʼязаний з текою, назва якої є хешем його графа залежностей. В результаті, всі проєкти в системі можуть звʼязати свої залежності з цим спільним місцем на диску. Цей підхід концептуально подібний до того, як NixOS керує пакунками, використовуючи хеші графів залежностей для створення ізольованих та спільних тек пакунків у сховищі Nix.
Це не слід плутати з глобальним сховищем адресованого вмісту. Фактичні файли пакунків, як і раніше, жорстко повʼязані зі сховищем, що адресується за вмістом, але замість того, щоб бути повʼязаними безпосередньо з
node_modules/.pnpm
, вони повʼязані з глобальним віртуальним сховищем.
Використання глобального віртуального сховища може значно прискорити встановлення, якщо доступний «теплий» кеш. Однак у середовищі CI (де кеш зазвичай відсутній) це може сповільнити встановлення. Якщо pnpm виявляє, що він працює в CI, цей параметр автоматично вимикається.
Налаштування сховища
storeDir
- Стандартно:
- Якщо встановлено змінну середовища $PNPM_HOME, тоді $PNPM_HOME/store
- Якщо встановлено змінну середовища $XDG_DATA_HOME, тоді $XDG_DATA_HOME/pnpm/store
- У Windows: ~/AppData/Local/pnpm/store
- В macOS: ~/Library/pnpm/store
- У Linux: ~/.local/share/pnpm/store
- Тип: path
Місце, де зберігаються всі пакунки на диску.
Сховище завжди має бути на тому самому диску, на якому відбувається встановлення, тому на кожному диску буде одне сховище. Якщо на поточному диску є домашня тека, то сховище створюється всередині неї. Якщо на диску немає домашньої теки, то сховище створюється у корені файлової системи. Наприклад, якщо встановлення відбувається у файлову систему, змонтовану за адресою /mnt
, то сховище буде створено за адресою /mnt/.pnpm-store
. Те ж саме стосується і систем Windows.
Можна встановити сховище з іншого диска, але у цьому випадку pnpm копіюватиме пакунки зі сховища, а не звʼязуватиме їх жорсткими посиланнями, оскільки жорсткі посилання можливі лише у тій самій файловій системі.
verifyStoreIntegrity
- Стандартно: true
- Тип: Boolean
Стандартно, якщо файл у сховищі було змінено, вміст цього файлу перевіряється перед звʼязуванням його з node_modules
проєкту. Якщо verifyStoreIntegrity
встановлено у false
, файли у сховищі з адресованим вмістом не буде перевірено під час встановлення.
useRunningStoreServer
Застаріла функція
- Стандартно: false
- Тип: Boolean
Дозволяє встановлення лише з сервером сховища. Якщо жоден сервер сховища не запущено, інсталяція завершиться невдало.
strictStorePkgContentCheck
- Стандартно: true
- Тип: Boolean
Деякі реєстри дозволяють публікувати один і той самий контент з різними назвами пакунків та/або версіями. Це порушує перевірку дійсності пакунків у сховищі. Щоб уникнути помилок при перевірці назв і версій таких пакунків у сховищі, ви можете встановити параметр strictStorePkgContentCheck
у значення false
.
Параметри Lockfile
файл блокування
- Стандартно: true
- Тип: Boolean
Якщо встановлено false
, pnpm не читатиме та не створюватиме файл pnpm-lock.yaml
.
preferFrozenLockfile
- Стандартно: true
- Тип: Boolean
Якщо встановлено значення true
і наявний pnpm-lock.yaml
задовольняє директиві залежностей package.json
, виконується headless встановлення. Встановлення headless пропускає визначення всіх залежностей, оскільки йому не потрібно змінювати файл блокування.
lockfileIncludeTarballUrl
- Стандартно: false
- Тип: Boolean
Додайте повну URL-адресу tar-файлу пакунка до кожного запису у pnpm-lock.yaml
.
gitBranchLockfile
- Стандартно: false
- Тип: Boolean
Якщо встановлено значення true
, згенерований файл блокування після встановлення буде названо на основі поточної назви гілки, щоб повністю уникнути конфліктів при злитті. Наприклад, якщо поточна назва гілки feature-foo
, то відповідна назва файлу блокування буде pnpm-lock.feature-foo.yaml
замість pnpm-lock.yaml. Зазвичай використовується разом з аргументом командного рядка
--merge-git-branch-lockfilesабо за допомогою параметра
mergeGitBranchLockfilesBranchPatternу файлі
pnpm-workspace.yaml`.
mergeGitBranchLockfilesBranchPattern
- Стандартно: null
- Тип: Array або null
Ця конфігурація відповідає назві поточної гілки, щоб визначити, чи потрібно обʼєднувати всі файли lockfile гілки git. Стандартно вам потрібно вручну передати параметр командного рядка --merge-git-branch-lockfiles
. Ця конфігурація дозволяє автоматично завершити цей процес.
Наприклад:
mergeGitBranchLockfilesBranchPattern:
- main
- release*
Ви також можете виключити шаблони за допомогою !
.
peersSuffixMaxLength
- Стандартно: 1000
- Тип: number
Максимальна довжина суфікса ідентифікаторів прямих залежностей, що додається до ключів залежностей у файлі блокування. Якщо суфікс довший, він замінюється хешем.
Реєстр та параметри автентифікації
registry
- Стандартно: https://registry.npmjs.org/
- Тип: url
Базова URL-адреса реєстру пакунків npm (включно з кінцевою косою рискою).
<scope>:registry
Реєстр npm, який слід використовувати для пакунків вказаної області доступу. Наприклад, встановлення @babel:registry=https://example.com/packages/npm/
призведе до того, що при використанні pnpm add @babel/core
або будь-якого пакунка з діапазоном @babel
, пакунок буде отримано з https://example.com/packages/npm
, а не зі стандартного реєстру.
<URL>:_authToken
Визначає токен автентифікації на предʼявника, який буде використовуватися при доступі до вказаного реєстру. Наприклад:
//registry.npmjs.org/:_authToken=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Ви також можете використовувати змінну оточення. Наприклад:
//registry.npmjs.org/:_authToken=${NPM_TOKEN}
Або ви можете використовувати змінну оточення безпосередньо, не змінюючи .npmrc
взагалі:
npm_config_//registry.npmjs.org/:_authToken=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
<URL>:tokenHelper
Помічник токена — це виконуваний файл, який виводить токен авторизації. Його можна використовувати в ситуаціях, коли authToken не є постійним значенням, а регулярно оновлюється, коли скрипт або інший інструмент може використовувати наявний токен оновлення для отримання нового токену доступу.
Конфігурація шляху до помічника має бути абсолютним шляхом, без аргументів. З міркувань безпеки дозволено встановлювати це значення лише у файлі .npmrc
користувача. Інакше проєкт може помістити значення у локальний файл .npmrc
і запустити довільні виконувані файли.
Встановлення помічника токенів для стандартного реєстру:
tokenHelper=/home/ivan/token-generator