Как перевести существующий проект на Vite+

Чтобы перевести существующий проект на Vite+, создайте новую ветку и запустите vp migrate в корне проекта или рабочего пространства. Прежде чем какие-либо файлы изменятся, изучите выведенный план. Затем проверьте результат командами vp install, vp check, vp test и vp build (или vp pack для библиотеки) и только после этого обновляйте CI.

Перевод рабочего репозитория с пятью отдельными конфигурациями инструментов на новый тулчейн выглядит мелочью в заголовке PR, а на деле может занять целый спринт. Обычно проблемы начинаются уже после того, как автоматическая часть отработала: важно, что она сконвертировала, а что нет.

Это руководство предназначено для проектов, которые уже используют Vite, Vitest, ESLint и Prettier. В нём рассказывается, что меняет vp migrate, что остаётся на ваше усмотрение, что нужно проверить после миграции и как обновить GitHub Actions и GitLab CI. Если сначала нужен обзор Vite+ и его команд, начните со статьи Getting Started with Vite+. Vite+ 1.0 вышел 28 сентября 2026 года под лицензией MIT.

Кому стоит переходить на Vite+ и что это даёт?

Миграция подходит командам, которые поддерживают отдельные конфигурации для Vite, Vitest, ESLint, Prettier и бандлера библиотек вроде tsup или tsdown. После миграции у вас остаются одна зависимость vite-plus и один файл vite.config.ts с настройками для dev-сервера, тестов, линтинга, форматирования и сборки пакетов. tsup входит в число поддерживаемых источников миграции, поэтому TypeScript-библиотеку, собираемую tsup, тоже можно перенести. Однако будьте готовы к доработкам: в руководстве по миграции прямо сказано, что большинству проектов после выполнения команды потребуются ручные правки.

Что нужно подготовить перед запуском vp migrate?

Выполняйте миграцию на Vite+ в отдельной ветке и с чистым рабочим деревом. Тогда диф будет содержать только изменения миграции, и от него легко избавиться.

git switch -c chore/migrate-vite-plus
git status   # should report a clean tree

Перед началом проверьте три условия:

• Vite 7 или новее. В более старых проектах сначала нужно обновить Vite. Об изменениях этого релиза рассказывается в статье What’s New in Vite 7.
• Vitest 4 или новее. Перед миграцией обновите старые тестовые наборы до v4.
• Node.js ^22.18.0 || ^24.11.0 || >=26.0.0, согласно руководству по обновлению до Vitest 5.

Сначала выполните все необходимые обновления исходных инструментов и проверьте их, после чего сохраните текущий lock-файл и установленные пакеты: мигратор использует их, чтобы определить исходную версию Vitest.

Запустите vp migrate и изучите план

vp migrate без аргументов выполняет миграцию текущего каталога. Перед записью файлов команда показывает запланированные изменения. Чтобы перенести проект из другого каталога, передайте путь к нему.

vp migrate                    # interactive, migrates the current directory
vp migrate ./path/to/project  # migrate another directory
vp migrate --no-interactive   # scripted runs

Команда migrate поддерживает следующие флаги:

• --no-interactive — запуск без интерактивных запросов.
• --agent <name> / --no-agent — включает или отключает создание файлов с инструкциями для AI-агентов.
• --editor <name> / --no-editor — включает или отключает запись конфигурации редактора.
• --hooks / --no-hooks — включает или отключает настройку git-хуков.

В монорепозитории единственная допустимая цель для vp migrate — корень рабочего пространства. Lock-файлы, каталоги и настройки пакетного менеджера, которые переписывает команда, относятся ко всем пакетам рабочего пространства, поэтому запускайте её один раз из корня, а не для каждого пакета по отдельности.

Что vp migrate конвертирует, а что оставляет без изменений?

vp migrate обновляет зависимости, переписывает импорты, объединяет конфигурацию инструментов в vite.config.ts, обновляет скрипты в package.json и форматирует изменённые файлы. Существующие инструменты для git-хуков команда намеренно не трогает.

Импорты в тестах переключаются с исходного Vitest на реэкспорты из vite-plus, который включает Vitest 5. Расширения типов (type augmentations) по-прежнему ссылаются на исходный пакет vitest:

// before
import { defineConfig } from 'vitest/config'
import { describe, it, expect } from 'vitest'

// after
import { defineConfig } from 'vite-plus'
import { describe, it, expect } from 'vite-plus/test'

declare module 'vitest' {
  // unchanged: augmentations keep targeting upstream vitest
}

Если вы сохраняете инструмент для хуков, lint-staged тоже остаётся, поскольку vp staged читает только блок staged в vite.config.ts. Переключаться на него придётся вручную:

import { defineConfig } from 'vite-plus'

export default defineConfig({
  staged: {
    '*.{js,ts,tsx}': 'vp check --fix',
  },
})

Для библиотек на tsdown версии ниже 0.23 (или если установленную версию определить не удалось) миграция сохраняет прежние значения по умолчанию. Она добавляет deps.resolveDepSubpath: true в блок pack, если этот параметр не задан, а также attw.profile: 'strict', если проверки ATTW включены, но профиль не указан. Полный список преобразований приведён в правилах миграции.

Как проверить проект после миграции?

Запустите vp install, vp check, vp test и vp build (или vp pack для библиотеки) и изучите результат каждой команды перед коммитом. Поскольку миграция прогоняет форматтер по изменённым файлам, просматривайте изменения форматирования отдельно от изменений зависимостей, конфигурации и импортов. Иначе диф с переформатированием может скрыть изменения логики.

Перед коммитом прочитайте отчёт, который формирует миграция. Если у вас есть тесты в браузерном режиме, тесты с покрытием или бенчмарки, запустите их отдельно.

Что делать, если правила линтинга или форматирования не перенеслись?

Миграция по возможности конвертирует flat-конфигурацию ESLint в Oxlint, а конфигурацию Prettier — в Oxfmt, однако не у каждого правила ESLint есть аналог в Oxlint. vp migrate выводит список неподдерживаемых правил, которые были пропущены. Если важное для вас правило не перенеслось, оставьте исходный инструмент в виде скрипта проекта и запускайте его через vp run:

{ "scripts": { "lint:eslint": "eslint ." } }

vp run lint:eslint

Это сработает, только если скрипт ESLint сохранился после миграции — то есть если вы отказались от конвертации ESLint/Prettier в интерактивном запросе или используете устаревший .eslintrc. В противном случае после миграции верните пакет, конфигурацию и скрипт вручную. Учтите, что vp test всегда запускает встроенную команду тестирования, а vp run test — тот скрипт test, который указан в package.json.

Если Node или пакетный менеджер резолвятся не в ту версию, запустите vp env doctor для диагностики.

Как обновить CI для Vite+?

В CI action для настройки Vite+ заменяет отдельные шаги настройки Node, пакетного менеджера, установки зависимостей и кеширования, а задачи напрямую вызывают команды vp. В GitHub Actions setup-vp устанавливает зависимости, если не задан параметр run-install: false:

name: CI
on:
  push:
    branches: [main]
  pull_request:

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: voidzero-dev/setup-vp@<setup-vp-version>
        with:
          node-version: '24'
          cache: true
      - run: vp check
      - run: vp test
      - run: vp build

Для GitLab руководство по CI предписывает подключить удалённый шаблон setup-vp.yml, расширить .setup-vp и использовать образ, в котором уже есть Node:

include:
  # copy the exact remote URL from the Vite+ CI guide
  - remote: 'https://raw.githubusercontent.com/voidzero-dev/setup-vp/<setup-vp-version>/gitlab/setup-vp.yml'
    inputs:
      setup-ref: '<setup-vp-version>'

check:
  extends: .setup-vp
  image: node:24
  # caching uses GitLab's native cache: keyword
  script:
    - vp check
    - vp test
    - vp build

Фиксируйте setup-vp на конкретном теге релиза или SHA коммита, а не на v1, поскольку VoidZero больше не обновляет этот тег. Найдите в своих workflow вхождения setup-vp@v1 и замените их. В GitLab версия указывается дважды (в URL в include и в setup-ref), и при обновлении обе нужно менять вручную.

Заключение

Миграция на Vite+ проходит гладко, если воспринимать vp migrate как первый шаг, а не как всю работу целиком. Изучите план, разделяйте изменения форматирования и логики, выполните четыре проверочные команды и зафиксируйте версию setup-vp в CI до слияния. Дальше создайте ветку, запустите vp migrate и разберите предупреждения, которые команда выведет для хуков и правил линтинга.

Часто задаваемые вопросы

Что делает vp migrate в проекте, который уже использует Vite+?

Команда только обновляет тулчейн. Она обновляет зависимости и настройки пакетного менеджера во всех пакетах рабочего пространства до версий, поставляемых с CLI, который выполняет миграцию, и финализирует импорты. Первичная настройка — git-хуки, файлы для редактора и агентов, миграция линтинга — при этом пропускается. Чтобы выполнить и эти действия, передайте флаг --full. Предварительно запустите vp upgrade, чтобы глобальный CLI получил актуальные правила миграции.

Нужно ли запускать vp migrate из node_modules самого проекта?

Нет. Руководство по миграции Vite+ не рекомендует запускать миграцию через node_modules/.bin/vp старого проекта. Используйте глобальный vp или загрузите нужный релиз командой npx --package=vite-plus@version vp migrate либо её аналогом через pnpm dlx. Так целевой CLI загружается без предварительной замены старых зависимостей проекта, и мигратор по-прежнему может определить исходную версию Vitest.

Какие пакетные менеджеры поддерживает Vite+ после миграции?

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

Как узнать, какие правила ESLint были отброшены при миграции?

vp migrate сообщает о неподдерживаемых правилах ESLint, которые пропускаются при конвертации в Oxlint. Эта возможность появилась в Vite+ 0.3.2, чтобы вы могли оценить, каких проверок лишаетесь. Изучите этот список перед коммитом, а затем верните нужные правила, сохранив ESLint в виде скрипта проекта и запуская его через vp run.