Управление пакетами

vp определяет и запускает менеджер пакетов текущего рабочего пространства. Эти команды доступны как в глобальном CLI, так и в локальном CLI проекта.

Обзор

Используйте Vite+ для управления зависимостями в pnpm, npm, Yarn и Bun. Вместо переключения между pnpm install, npm install, yarn install и bun install, вы можете продолжать использовать vp install, vp add, vp remove и остальные команды управления пакетами Vite+.

Vite+ определяет менеджер пакетов из корня рабочего пространства в следующем порядке:

1. packageManager в package.json
2. devEngines.packageManager в package.json
3. pnpm-workspace.yaml
4. pnpm-lock.yaml
5. yarn.lock или .yarnrc.yml
6. package-lock.json
7. bun.lock или bun.lockb
8. .pnpmfile.cjs или pnpmfile.cjs
9. bunfig.toml
10. yarn.config.cjs

Если ни один из этих файлов не найден, vp по умолчанию использует pnpm. Vite+ автоматически загружает соответствующий менеджер пакетов и использует его для выполняемой команды, но обнаружение менеджера пакетов никогда не изменяет package.json. Если в проекте необходимо явно указать точную версию, используйте vp env pin <package-manager>@<version>.

Поле devEngines.packageManager может содержать один объект или массив объектов, а значение свойства version может задаваться не только конкретной версией, но и диапазоном версий согласно правилам семантического версионирования:

{
  "devEngines": {
    "packageManager": {
      "name": "pnpm",
      "version": "^11.0.0",
      "onFail": "download"
    }
  }
}

Если указан диапазон версий, по возможности выбирается уже загруженная версия, которая ему соответствует; в противном случае используется самая новая подходящая версия из реестра npm. Сам диапазон остаётся источником истины — Vite+ никогда не заменяет его точной фиксированной версией в поле packageManager. Если указаны и packageManager, и devEngines.packageManager, для выбора используется поле packageManager, а Vite+ выводит предупреждение, если оно не соответствует ограничениям из devEngines (подробности можно посмотреть с помощью vp env doctor).

В настоящее время Vite+ всегда загружает указанный менеджер пакетов (поведение onFail: "download"). Другие значения onFail принимаются, но пока не отличаются по поведению.

Явно указанное поле packageManager (или запись в devEngines.packageManager) также влияет на соответствующие shim-команды менеджеров пакетов. Например, если в проекте указано packageManager: "npm@10.9.4", команды npm и npx будут использовать npm 10.9.4. Аналогично работают и другие пары алиасов: pnpm/pnpx, yarn/yarnpkg и bun/bunx. Несоответствующие инструменты не подменяются автоматически: например, команда npm в проекте на pnpm всё равно будет разрешаться как npm.

Использование

vp install

Типовые сценарии установки:

vp install
vp install --frozen-lockfile
vp install --lockfile-only
vp install --filter web
vp install -w

vp install сопоставляется с корректным поведением установки для обнаруженного менеджера пакетов, включая правильные флаги работы с lock-файлами для pnpm, npm, Yarn и Bun.

Глобальные пакеты

Используйте флаг -g для установки, обновления или удаления глобально установленных пакетов:

• vp install -g <pkg> — устанавливает пакет глобально
• vp uninstall -g <pkg> — удаляет глобальный пакет
• vp update -g [pkg] — обновляет один глобальный пакет или все сразу
• vp list -g [pkg] — выводит список глобальных пакетов
• vp outdated -g [pkg] выводит список устаревших пакетов

При обновлении сохраняется спецификатор версии, с которым пакет был установлен: если пакет был установлен по dist-тегу (например, vp install -g some-pkg@nightly), он будет обновляться до самой новой версии этого тега, а если была указана версия в виде диапазона, обновление останется в пределах этого диапазона. Чтобы переключиться на другой спецификатор, переустановите пакет с ним (например, vp update -g some-pkg@latest), либо передайте флаг --latest команде vp update -g, чтобы перевести пакеты на тег latest и удалить сохранённые спецификаторы. Команда vp outdated -g показывает как последнюю версию, соответствующую сохранённому спецификатору (Wanted), так и самую новую версию, доступную по тегу latest.

ПРЕДУПРЕЖДЕНИЕ

Эти команды НЕ взаимодействуют с каталогом глобальной установки используемого пакетного менеджера.

Вместо этого Vite+ хранит глобальные пакеты в каталоге packages/ внутри определённого каталога данных. Эти пакеты остаются доступными для разных версий Node.js.

Поэтому такие команды, как vp link, не влияют на глобальные пакеты Vite+, и они не будут отображаться в выводе vp list -g.

Управление зависимостями

Vite+ предоставляет все привычные команды управления пакетами:

• vp install — устанавливает текущий граф зависимостей проекта
• vp add <pkg> — добавляет пакеты в dependencies, используйте -D для devDependencies
• vp remove <pkg> — удаляет пакеты
• vp update — обновляет зависимости
• vp dedupe — сокращает количество дублирующихся записей зависимостей там, где это поддерживается менеджером пакетов
• vp outdated — показывает доступные обновления
• vp list — показывает установленные пакеты
• vp why <pkg> — объясняет, почему пакет присутствует в проекте
• vp info <pkg> — показывает метаданные пакета из реестра
• vp rebuild — пересобирает нативные модули (например, после смены версии Node.js)
• vp link и vp unlink — управляют локальными связями пакетов
• vp dlx <pkg> — запускает бинарный файл пакета без добавления его в проект
• vp pm <command> — передаёт исходную команду конкретному менеджеру пакетов, если требуется поведение вне унифицированного набора команд vp

Справочник команд

Установка

Используйте vp install, если хотите установить именно те зависимости, которые описаны в текущих package.json и lock-файле.

• vp install — стандартная команда установки
• vp install --frozen-lockfile — завершится ошибкой, если потребуется изменить lock-файл
• vp install --no-frozen-lockfile — явно разрешает обновление lock-файла
• vp install --lockfile-only — обновляет только lock-файл без полной установки
• vp install --prefer-offline и vp install --offline — предпочитают или требуют использование пакетов из локального кэша
• vp install --ignore-scripts — пропускает сценарии жизненного цикла
• vp install --filter <pattern> — ограничивает установку указанными пакетами в монорепозитории
• vp install -w — выполняет установку в корне рабочего пространства

Зависимости из Git и удалённых tarball-архивов (npm v12+)

npm v12 по умолчанию перестаёт разрешать зависимости из Git (github:, git+https:) и URL удалённых tarball-архивов; такие установки завершаются с ошибками EALLOWGIT / EALLOWREMOTE. Чтобы снова разрешить их, настройте параметры allow-git / allow-remote npm для конкретного проекта.

Глобальная установка

Используйте эти команды, если хотите сделать инструменты, управляемые менеджером пакетов, доступными вне конкретного проекта.

• vp install -g typescript
• vp uninstall -g typescript
• vp update -g
• vp list -g
• vp outdated -g

Добавление и удаление

Используйте vp add и vp remove для повседневного управления зависимостями вместо ручного редактирования package.json.

• vp add react
• vp add -D typescript vitest
• vp add -O fsevents
• vp add --save-peer react
• vp add react --ignore-scripts
• vp remove react
• vp remove --filter web react

Обновление, дедупликация и проверка устаревших пакетов

Используйте эти команды для поддержки графа зависимостей в актуальном состоянии.

• vp update — обновляет пакеты до более новых версий
• vp outdated — показывает пакеты, для которых доступны новые версии
• vp dedupe — просит менеджер пакетов по возможности объединить дублирующиеся зависимости

Анализ зависимостей

Используйте эти команды, чтобы понять текущее состояние зависимостей.

• vp list — показывает установленные пакеты
• vp why react — объясняет, почему установлен react
• vp info react — показывает метаданные из реестра, такие как версии и dist-tags

Эти команды показывают пакеты, установленные пакетным менеджером. Они не показывают инструменты, которые Vite+ включает в свой состав или компилирует. Выполните vp toolchain [tool], чтобы посмотреть эти инструменты, включая Vite, Rolldown и Oxc. Для более наглядного вывода vp why показывает подсказку, когда пакет также предоставляется Vite+.

Пересборка

Используйте vp rebuild, когда нативные модули необходимо перекомпилировать, например после смены версии Node.js или если дополнение на C/C++ не удаётся загрузить.

• vp rebuild — пересобирает все нативные модули
• vp rebuild <package...> — пересобирает только указанные пакеты
• vp rebuild -- <args> — передаёт дополнительные аргументы базовому менеджеру пакетов

vp rebuild
vp rebuild better-sqlite3 sharp
vp rebuild -- --update-binary

vp rebuild является сокращением для vp pm rebuild.

Начиная с pnpm v10, команда vp rebuild без указания пакета пересобирает только те пакеты, чьи сценарии сборки перечислены в onlyBuiltDependencies (или были одобрены через pnpm approve-builds). Чтобы принудительно пересобрать пакет в обход механизма подтверждения, укажите его имя явно.

Сценарии сборки зависимостей (npm v12+)

npm v12 пропускает сценарии установки зависимостей (preinstall / install / postinstall, включая неявные сборки node-gyp), если поле allowScripts в package.json не разрешает их выполнение; установка завершается успешно, а npm предупреждает о пропущенных сценариях. vp pm approve-builds управляет этим списком разрешённых сценариев:

• vp pm approve-builds <pkg...> разрешает выполнение сценариев указанных пакетов (npm approve-scripts)
• vp pm approve-builds !<pkg...> запрещает их выполнение (npm deny-scripts)
• vp pm approve-builds --all разрешает выполнение всех пакетов, ожидающих подтверждения
• vp pm approve-builds выводит список пакетов, сценарии которых ещё не разрешены

Подтверждение лишь добавляет пакет в список разрешённых: сценарии, пропущенные во время предыдущей установки, не будут запущены, пока вы не выполните vp rebuild <pkg>. В npm 11.16 - 11.x работают те же команды, но npm воспринимает этот список лишь как рекомендацию и всё равно выполняет сценарии.

Дополнительно

Используйте эти команды, когда требуется более низкоуровневое поведение менеджера пакетов.

• vp link и vp unlink — управляют локальными ссылками для разработки
• vp dlx create-vite — запускает бинарный файл пакета без сохранения его в зависимостях
• vp pm <command> — напрямую передаёт команду выбранному менеджеру пакетов

Примеры:

vp pm config get registry
vp pm cache clean -- --force
vp pm audit --json

Поэтапная публикация

vp pm stage предоставляет доступ к рабочему процессу поэтапной публикации из npm: сборка загружается в промежуточную область (без 2FA, удобно для CI), после чего сопровождающий проекта может утвердить или отклонить её с доверенного устройства (с использованием 2FA). Команда автоматически адаптируется под обнаруженный менеджер пакетов.

vp pm stage publish              # загрузить пакет в staging (без 2FA)
vp pm stage list                 # показать список staged-версий
vp pm stage view <stage-id>      # просмотреть staged-версию
vp pm stage download <stage-id>  # скачать staged-архив
vp pm stage approve <stage-id>   # опубликовать в основном реестре (2FA)
vp pm stage reject <stage-id>    # отклонить staged-версию (2FA)

• Для pnpm (pnpm stage, требуется pnpm ≥ 11.3) и npm (npm stage, требуется npm ≥ 11.15 и Node ≥ 22.14) команды передаются напрямую.
• Yarn (Berry) использует свой npm-плагин (yarn npm publish --staged, yarn npm stage …); команды view и download выполняются через npm.
• Yarn Classic и Bun не поддерживают поэтапную публикацию и используют npm stage в качестве резервного варианта.

Проверка целостности менеджера пакетов

Закреплённая версия packageManager может содержать хеш целостности (yarn@4.17.1+sha512.…). Команда corepack use записывает этот хеш. Vite+ вычисляет хеш того же артефакта, что и Corepack:

• извлечённого бинарного файла CLI (bin/yarn.js) для Yarn 2 и более поздних версий;
• tarball-архива npm-пакета для npm, pnpm и Yarn Classic.

Vite+ вычисляет хеш CLI один раз при установке Yarn и сохраняет проверенную им закреплённую версию. При последующем запуске команда сравнивает свою закреплённую версию с этой записью. Если закреплённая версия не совпадает с сохранённой записью, проверка завершается ошибкой, и выполнение команды прекращается. Corepack хранит аналогичную запись в собственном кэше.