Node-Modules & Hoisting Settings

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

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. Законні причини для використання цього налаштування:
  1. Ваші інструменти погано працюють із символічними посиланнями. Проєкт на React Native, швидше за все, буде працювати тільки в тому випадку, якщо ви використовуєте піднятий node_modules.
  2. Ваш проєкт буде розгорнуто на безсерверний хостинг. Деякі безсерверні провайдери (наприклад, AWS Lambda) не підтримують symlinks. Альтернативним розвʼязання цієї проблеми є пакування програми перед розгортанням.
  3. Якщо ви хочете опублікувати свій пакунок за допомогою "bundledDependencies".
  4. Якщо ви використовуєте Node.js із прапорцем --preserve-symlinks.
• pnp — без node_modules. Plug'n'Play — це інноваційна стратегія для Node, яка використовується Yarn Berry. Рекомендується також встановити параметр symlink у значення false, якщо ви використовуєте pnp як ваш компонувальник.

nodeExperimentalPackageMap

Додано у: v11.8.0

• Стандартно: false
• Тип: Boolean

When true, pnpm injects the generated node_modules/.package-map.json into pnpm-managed Node.js script environments by adding Node's --experimental-package-map option to NODE_OPTIONS.

The package map is generated during isolated and hoisted installs. This setting only controls whether pnpm passes the generated map to scripts.

CLI and environment configuration use the kebab-case name node-experimental-package-map.

nodeExperimentalPackageMap: true

nodePackageMapType

Додано у: v11.8.0

• Default: standard
• Type: standard, loose

Controls how node_modules/.package-map.json is generated.

• standard - only declared dependencies are available through the package map.
• loose - also maps packages that are reachable through the installed node_modules layout, which can allow undeclared hoisted dependencies to resolve.

CLI and environment configuration use the kebab-case name node-package-map-type.

nodePackageMapType: loose

symlink

• Стандартно: 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.

virtualStoreOnly

Додано у: v11.0.0

• Стандартно: false
• Тип: Boolean

Якщо встановлено значення true, pnpm заповнює віртуальний репозиторій без створення символьних посилань імпортера, підйому, посилань на бінарні файли або запуску скриптів життєвого циклу. Це корисно для попереднього заповнення сховища (наприклад, у збірках Nix) без створення зайвих артефактів на рівні проєкту. Команда pnpm fetch використовує цей режим внутрішньо.

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
• Тип: Boolean

нотатка

У pnpm v11 глобальні встановлення (pnpm add -g) та pnpm dlx стандартно використовують глобальне віртуальне сховище.

Якщо увімкнено, node_modules містить лише символьні посилання на центральне віртуальне сховище, а не на node_modules/.pnpm. Стандартно, це центральне сховище розташовано за адресою <store-path>/links (використовуйте pnpm store path, щоб знайти <store-path>).

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

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

Використання глобального віртуального сховища може значно прискорити встановлення, якщо доступний «теплий» кеш. Однак у середовищі CI (де кеш зазвичай відсутній) це може сповільнити встановлення. Якщо pnpm виявляє, що він працює в CI, цей параметр автоматично вимикається.

important

Для підтримки піднятих залежностей при використанні глобального віртуального сховища pnpm покладається на змінну оточення NODE_PATH. Це дозволяє Node.js розпізнавати пакунки з піднятої теки node_modules. Однак цей обхідний шлях не працює з модулями ESM, оскільки Node.js більше не враховує NODE_PATH при використанні ESM.

Якщо ваші залежності є залежностями ESM і вони імпортують пакунки не оголошені у власному package.json (що вважається поганою практикою), ви, ймовірно, зіткнетеся з помилками при обробці. Виправити це можна двома способами:

• Використовуйте packageExtensions для явного додавання відсутніх залежностей.
• Додайте конфігураційну залежність @pnpm/plugin-esm-node-path до вашого проєкту. Цей втулок реєструє власний завантажувач ESM, який відновлює підтримку NODE_PATH для ESM, дозволяючи коректно вирішувати підняті залежності.

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

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, щоб підняти їх для вас.

hoistingLimits

Added in: v11.5.0

• Default: none
• Type: none, workspaces, dependencies

Controls how far dependencies are hoisted when using nodeLinker: hoisted. This setting mirrors Yarn's nmHoistingLimits.

• none - hoist as far as possible (the default).
• workspaces - hoist only as far as each workspace package, preventing dependencies from being hoisted above the workspace package that depends on them.
• dependencies - hoist only up to each workspace package's direct dependencies, preventing transitive dependencies from being hoisted into the workspace package's node_modules.