Чтобы выровнять зависимость между пакетами npm на Mac, сначала сравните диапазоны версий в файле package.json каждого рабочего пространства (workspace), определите, какой общий диапазон версий подходит для каждого пакета, затем обновите каждое затронутое рабочее пространство и заново сгенерируйте корневой lock-файл. npm workspaces позволяют адресовать пакеты из корня репозитория, но не предоставляют встроенной команды, которая сканирует каждый манифест и автоматически делает версии зависимостей идентичными.

1. Проверьте, что репозиторий использует npm workspaces

В Терминале перейдите в корень репозитория и проверьте его конфигурацию:

cd "/path/to/your/repository"
npm --version
npm pkg get workspaces

Корневой package.json должен определять пути к рабочим пространствам, а каждый пакет должен иметь собственный package.json. Функция npm workspaces связывает эти локальные пакеты во время установки и позволяет командам выбирать одно или несколько рабочих пространств по имени или пути. Если npm pkg get workspaces ничего не возвращает, проверьте пакетный менеджер и структуру репозитория перед использованием команд npm workspace. npm Workspaces

2. Сравните объявления зависимостей

Выполните поиск нужной зависимости по отслеживаемым манифестам. Например, в Терминале macOS можно использовать grep без установки дополнительных инструментов:

grep -n '"typescript"' package.json packages/*/package.json

Замените typescript на имя нужной зависимости. Это быстрая текстовая проверка, поэтому просмотрите соответствующие разделы в каждом манифесте, чтобы увидеть, находится ли пакет в dependencies, devDependencies, peerDependencies или optionalDependencies. Эти поля описывают разные роли; не перемещайте зависимость между ними только ради совпадения строк с версиями. Для более полного аудита изучите манифест каждого рабочего пространства в редакторе или воспользуйтесь командой вывода списка npm с поддержкой рабочих пространств:

npm ls typescript --workspaces --depth=0

Диапазоны в манифестах и дерево установленных пакетов отвечают на разные вопросы: первые показывают, что разрешает каждый пакет, в то время как npm ls сообщает о фактическом состоянии установленных зависимостей. Lock-файл npm фиксирует разрешенные версии, но он не заменяет допустимые диапазоны, объявленные в каждом package.json. npm ls package-lock.json and npm install

3. Выберите совместимую политику версий

Выберите версию, которая удовлетворяет требованиям потребителей пакетов и политике поддержки репозитория. Общий диапазон версий означает, что пакеты выражают одинаковый набор допустимых значений; это не гарантирует, что все вложенные или транзитивные копии разрешатся в один установленный экземпляр. Проверьте требования к peer-зависимостям и примечания к выпуску (release notes) на наличие критических изменений перед переводом пакетов на новую мажорную версию. Если потребителям требуется более широкий диапазон совместимости, фиксация одной и той же точной строки может быть неуместной; вместо этого согласуйте политику эквивалентных диапазонов.

Например, чтобы установить инструмент разработки одной и той же точной версии в двух рабочих пространствах с именами web и api, выполните из корня следующее:

npm install --save-dev --save-exact typescript@5.8.3 --workspace=web --workspace=api

Используйте версию, выбранную для вашего проекта; 5.8.3 приведена здесь лишь для примера. Команда npm install принимает селекторы рабочих пространств и сохраняет пакет в манифесте каждого выбранного пакета. Флаг --save-exact записывает точную версию вместо обычного для npm оператора диапазона. Для зависимостей времени выполнения (runtime) используйте соответствующую категорию сохранения, например --save-prod, вместо --save-dev. npm install

Повторите команду с дополнительными селекторами рабочих пространств или запустите её для каждого рабочего пространства отдельно. Не предполагайте, что установка на корневом уровне обновит манифест каждого пакета: явно указывайте пакеты, чьи объявления должны измениться. Корневой пакет также можно намеренно включить с помощью --include-workspace-root, если он должен объявлять ту же зависимость.

4. Переустановите, проверьте diff и выполните верификацию

После обновления объявлений запустите установку в корне репозитория, чтобы npm согласовал дерево рабочих пространств и lock-файл:

npm install
npm ls typescript --workspaces --depth=0
git diff -- package.json package-lock.json packages/*/package.json

Убедитесь, что в каждом целевом манифесте указано согласованное объявление, а изменения в lock-файле соответствуют ожиданиям. Запустите соответствующие скрипты сборки или тестирования репозитория; одна только команда npm ls не подтверждает, что код работает с выбранной версией. Зафиксируйте корневой package-lock.json в системе контроля версий, если проект его отслеживает, чтобы участники команды могли воспроизвести разрешенное дерево при установке. npm package-lock documentation

Если npm сообщает о недействительной зависимости или конфликте peer-зависимостей, изучите пакет, указанный в ошибке, вместо того чтобы форсировать установку. Одному из рабочих пространств может требоваться другой совместимый диапазон, либо другая зависимость может налагать требование к peer-зависимости, требующее продуманного плана обновления.

Когда помогает npm dedupe

Команда npm dedupe может упростить дерево установленных зависимостей, перемещая совместимые зависимости выше, чтобы пакеты могли использовать их совместно. Она не перезаписывает диапазоны прямых зависимостей в package.json, поэтому сама по себе не может выровнять объявления. Используйте её только после проверки совместимости диапазонов, а затем просмотрите получившийся diff lock-файла. npm dedupe

Надежный результат — это продуманная политика, отраженная в манифесте каждого соответствующего рабочего пространства, повторно сгенерированный lock-файл и верификация затронутых пакетов. Это обеспечивает мейнтейнерам четкую картину того, что было выровнено, и оставляет несовместимые ограничения видимыми для принятия отдельного решения.

Источники