Локальный CLI проекта

В отличие от глобального CLI vp, vite-plus представляет собой npm-пакет, который содержит локальный CLI проекта vp и интегрированный фронтенд-инструментарий. Установите его как зависимость для разработки, если хотите зафиксировать версию инструментария в манифесте и lock-файле проекта или не хотите устанавливать отдельно глобальный CLI.

Локальный пакет включает Vite, Rolldown, Vitest, Oxlint, Oxfmt, tsdown, запуск задач Vite+ и команды менеджеров пакетов. Для его работы требуются уже установленный рантайм Node.js и менеджер пакетов.

Установка

В большинстве случаев мы рекомендуем использовать CLI Vite+ для установки в проект или создания нового проекта. Подробнее см. в разделах Создание проекта и Миграция на Vite+.

pnpm

pnpm dlx --package=vite-plus vp create

npm

npx --package=vite-plus vp create

Yarn

yarn dlx --package vite-plus vp create

Bun

bunx --package vite-plus vp create

Запускайте его бинарный файл через менеджер пакетов. Например:

./node_modules/.bin/vp migrate --help
./node_modules/.bin/vp check

В документации для удобства используются команды vp без префикса. Без глобального CLI добавляйте к интерактивным командам префикс локального исполнителя бинарных файлов вашего менеджера пакетов, например pnpm exec.

Ручная установка

Если вы вручную переносите проект на Vite+, сначала установите следующие dev-зависимости:

vp install -D vite-plus

Необходимо добавить переопределения в настройках вашего пакетного менеджера, чтобы другие пакеты использовали версии Vite+, а именно: указать vite как алиас для @voidzero-dev/vite-plus-core, а для vitest зафиксировать версию, которая входит в состав Vite+ (выполните vp --version), чтобы весь проект использовал одну и ту же копию Vitest вместе с vp test. Без фиксации версии vitest зависимость или пакет workspace может подтянуть другую версию Vitest, из-за чего внутренние компоненты Vitest (моки, expect, состояние раннера) окажутся разделены:

pnpm-workspace.yaml

overrides:
  vite: npm:@voidzero-dev/vite-plus-core@latest
  vitest: 4.1.11

npm / Bun package.json

"overrides": {
  "vite": "npm:@voidzero-dev/vite-plus-core@latest",
  "vitest": "4.1.11"
}

Yarn package.json

"resolutions": {
  "vite": "npm:@voidzero-dev/vite-plus-core@latest",
  "vitest": "4.1.11"
}

Зачем нужны эти настройки?

Зависимости и плагины могут напрямую импортировать vite или vitest, даже если ваш собственный код импортирует их из vite-plus. Эти переопределения согласуют их зависимости с инструментариями, которые использует Vite+:

• Алиас vite направляет такие импорты на основной пакет Vite+. Отдельные экземпляры Vite могут нарушать проверки идентичности во время выполнения: в issue #1391 сообщается, что TanStack Start возвращал ошибки 404 из-за проверки instanceof, выполнявшейся между двумя копиями. PR #2617 устраняет эту проблему на стороне CLI, используя один и тот же алиас для общего экземпляра Vite.
• Точная фиксация версии vitest гарантирует, что зависимости и vp test используют одну и ту же версию Vitest, предотвращая появление отдельных моков, экземпляров expect и состояния раннера. В PR #2365 это требование описано для ручной установки.

Поддерживайте алиас основного пакета в соответствии с установленной версией vite-plus, а при обновлении обновляйте фиксацию версии Vitest в соответствии с версией, входящей в состав пакета. В issue #2356 описано, как боты для обновления зависимостей могут независимо обновлять эти пакеты, оставляя несовместимые версии установленными одновременно.

Лучшие практики

Мы рекомендуем использовать глобальный CLI вместе с локальным CLI проекта. Глобальный CLI делает vp непосредственно доступным в терминале и передаёт команды разработки, такие как vp dev, vp build и vp test, установленному в проекте пакету vite-plus. Это обеспечивает удобный доступ к инструментарию, сохраняя при этом его версию под контролем проекта. При желании можно использовать только локальный CLI проекта.

Для проектов с открытым исходным кодом или любых проектов, над которыми работают несколько участников, мы рекомендуем добавлять в package.json скрипты, вызывающие vp, независимо от того, используете ли вы оба CLI или только локальный CLI проекта. Внутри скриптов vp автоматически разрешается из node_modules/.bin:

package.json

{
  "scripts": {
    "dev": "vp dev",
    "check": "vp check",
    "test": "vp test",
    "build": "vp build"
  }
}

После установки зависимостей проекта участники могут запускать эти скрипты через свой менеджер пакетов, например pnpm run dev или npm run dev, без необходимости устанавливать глобальный CLI.

Что входит в состав

Локальный CLI проекта можно использовать независимо для:

• vp dev, vp build и vp preview с Vite и Rolldown
• vp check, vp lint и vp fmt с Oxc
• vp test с Vitest
• vp pack с tsdown
• vp toolchain для просмотра версий, входящих в состав локального пакета проекта
• vp run и кэширования задач между рабочими пространствами
• команд менеджера пакетов с использованием рантайма Node.js, уже активного в вашей оболочке
• vp create, vp migrate и команд настройки проекта

Локальный пакет не может управлять установкой Vite+ на уровне машины. Для команд vp env, vp upgrade и vp implode требуется глобальный CLI. Обновляйте или удаляйте локальную установку только через свой менеджер пакетов.

Добавление глобального CLI позднее

Вы можете установить глобальный CLI в любое время, не изменяя зависимость проекта. Такие команды, как vp dev, vp build и vp test, продолжат использовать установленную в проекте версию vite-plus.

См. раздел Использование обоих CLI вместе, посвящённый правилам выбора.