So migrieren Sie ein bestehendes Projekt zu Vite+

Um ein bestehendes Projekt zu Vite+ zu migrieren, führen Sie vp migrate auf einem frischen Branch im Projekt- oder Workspace-Root aus. Lesen Sie den ausgegebenen Plan, bevor Dateien geändert werden, und prüfen Sie das Ergebnis anschließend mit vp install, vp check, vp test und vp build (bzw. vp pack bei einer Library), bevor Sie die CI anpassen.

Ein funktionierendes Repository mit fünf separaten Tool-Konfigurationen auf eine neue Toolchain umzustellen, ist genau die Art von Änderung, die im PR-Titel klein wirkt und dann einen ganzen Sprint verschlingt. Die Probleme beginnen meist erst, wenn der automatisierte Teil abgeschlossen ist: bei dem, was er konvertiert hat, und bei dem, was nicht.

Dieser Leitfaden richtet sich an Projekte, die bereits Vite, Vitest, ESLint und Prettier einsetzen. Er beschreibt, was vp migrate ändert, was Sie selbst erledigen müssen, was Sie danach prüfen sollten und wie Sie GitHub Actions und GitLab CI anpassen. Wenn Sie zunächst einen Überblick über Vite+ und seine Befehle benötigen, beginnen Sie mit Getting Started with Vite+. Vite+ 1.0 wurde am 28. September 2026 unter der MIT-Lizenz veröffentlicht.

Für wen lohnt sich die Migration zu Vite+ und was bringt sie?

Die Migration eignet sich für Teams, die separate Konfigurationen für Vite, Vitest, ESLint, Prettier und einen Library-Bundler wie tsup oder tsdown pflegen. Nach der Migration haben Sie eine einzige vite-plus-Abhängigkeit und eine einzige vite.config.ts, die die Einstellungen für Dev, Test, Lint, Format und Pack enthält. tsup ist eine unterstützte Migrationsquelle, sodass auch eine TypeScript-Library, die mit tsup gebündelt wird, übernommen werden kann. Rechnen Sie allerdings mit Nacharbeiten. Der Migrationsleitfaden stellt klar, dass die meisten Projekte nach Abschluss des Befehls noch manuell angepasst werden müssen.

Was brauchen Sie, bevor Sie vp migrate ausführen?

Führen Sie die Vite+-Migration auf einem eigenen Branch und mit einem sauberen Working Tree durch. So enthält der Diff ausschließlich Migrationsänderungen und lässt sich bei Bedarf problemlos verwerfen.

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

Prüfen Sie vorab diese drei Punkte:

• Vite 7 oder neuer. Ältere Projekte müssen zuerst Vite aktualisieren. What’s New in Vite 7 beschreibt die Änderungen in diesem Release.
• Vitest 4 oder neuer. Aktualisieren Sie ältere Test-Suites vor der Migration auf v4.
• Node.js ^22.18.0 || ^24.11.0 || >=26.0.0 gemäß dem Vitest-5-Upgrade-Guide.

Führen Sie notwendige Upstream-Upgrades zuerst durch und validieren Sie sie. Behalten Sie anschließend das bestehende Lockfile und die installierten Pakete bei. Der Migrator liest sie aus, um zu ermitteln, von welcher Vitest-Version Sie ausgehen.

vp migrate ausführen und den Plan lesen

Wird vp migrate ohne Argumente ausgeführt, migriert es das aktuelle Verzeichnis. Die geplanten Änderungen werden angezeigt, bevor Dateien geschrieben werden. Übergeben Sie einen Pfad, um ein Projekt in einem anderen Verzeichnis zu migrieren.

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

Der Befehl migrate akzeptiert folgende Flags:

• --no-interactive läuft ohne Rückfragen.
• --agent <name> / --no-agent steuert, ob Instruktionsdateien für Coding-Agents eingerichtet werden.
• --editor <name> / --no-editor steuert, ob eine Editor-Konfiguration geschrieben wird.
• --hooks / --no-hooks steuert, ob Git-Hooks eingerichtet werden.

In einem Monorepo ist der Workspace-Root das einzig gültige Ziel für vp migrate. Die Lockfiles, Catalogs und Paketmanager-Einstellungen, die der Befehl umschreibt, gehören zu allen Paketen im Workspace. Führen Sie ihn daher einmalig im Root aus und nicht Paket für Paket.

Was konvertiert vp migrate und was bleibt unverändert?

vp migrate aktualisiert Abhängigkeiten, schreibt Imports um, führt die Tool-Konfiguration in vite.config.ts zusammen, aktualisiert die Scripts in package.json und formatiert die geänderten Dateien. Bestehende Git-Hook-Tools werden bewusst nicht angetastet.

Test-Imports werden von Upstream-Vitest auf die Re-Exports in vite-plus umgestellt, das Vitest 5 mitbringt. Typ-Augmentierungen verweisen weiterhin auf das Upstream-Paket 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
}

Wenn Sie ein Hook-Tool beibehalten, bleibt auch lint-staged erhalten, da vp staged ausschließlich den staged-Block in vite.config.ts liest. Die Umstellung nehmen Sie manuell vor:

import { defineConfig } from 'vite-plus'

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

Bei Libraries mit einer tsdown-Version unter 0.23 (oder wenn die installierte Version nicht ermittelt werden kann) behält die Migration die bisherigen Standardwerte bei. Sie ergänzt deps.resolveDepSubpath: true im pack-Block, sofern Sie diesen Wert nicht gesetzt haben, und fügt attw.profile: 'strict' hinzu, wenn ATTW-Prüfungen aktiviert sind und kein Profil festgelegt ist. Die Migrationsregeln listen sämtliche Transformationen auf.

Wie prüfen Sie das migrierte Projekt?

Führen Sie vp install, vp check, vp test und vp build (bzw. vp pack bei einer Library) aus und überprüfen Sie jedes Ergebnis, bevor Sie committen. Da die Migration den Formatter über die geänderten Dateien laufen lässt, sollten Sie die Formatierungsänderungen getrennt von den Änderungen an Abhängigkeiten, Konfiguration und Imports reviewen. Andernfalls kann ein Formatierungs-Diff Logikänderungen verdecken.

Lesen Sie vor dem Commit den Review-Bericht, den die Migration erstellt. Wenn Sie Browser-Mode-, Coverage- oder Benchmark-Suites nutzen, führen Sie diese zusätzlich separat aus.

Was tun, wenn Lint- oder Format-Regeln nicht übernommen werden?

Die Migration konvertiert ESLint-Flat-Configs nach Oxlint und Prettier-Konfigurationen nach Oxfmt, soweit möglich. Allerdings hat nicht jede ESLint-Regel ein Oxlint-Pendant. vp migrate listet die nicht unterstützten Regeln auf, die übersprungen werden. Wenn eine Regel, auf die Sie angewiesen sind, nicht übernommen wird, behalten Sie das ursprüngliche Tool als Projekt-Script bei und führen es über vp run aus:

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

vp run lint:eslint

Das funktioniert nur, wenn das ESLint-Script die Migration übersteht. Das ist der Fall, wenn Sie die Abfrage zur ESLint-/Prettier-Konvertierung abgelehnt haben oder eine Legacy-.eslintrc verwenden. Andernfalls müssen Sie Paket, Konfiguration und Script nach der Migration selbst wieder hinzufügen. Beachten Sie, dass vp test immer den integrierten Testbefehl ausführt, während vp run test das test-Script aus package.json ausführt.

Falls Node oder der Paketmanager auf die falsche Version aufgelöst wird, können Sie das Problem mit vp env doctor diagnostizieren.

Wie passen Sie die CI für Vite+ an?

In der CI ersetzt die Vite+-Setup-Action die separaten Steps für Node, Paketmanager, Installation und Cache, und die Jobs rufen die vp-Befehle direkt auf. Auf GitHub Actions installiert setup-vp die Abhängigkeiten, sofern Sie nicht run-install: false setzen:

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

Auf GitLab sieht der CI-Leitfaden vor, dass Sie das Remote-Template setup-vp.yml einbinden, .setup-vp erweitern und ein Image verwenden, das Node bereits enthält:

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

Pinnen Sie setup-vp auf einen exakten Release-Tag oder Commit-SHA statt auf v1, da VoidZero diesen Tag nicht mehr aktualisiert. Durchsuchen Sie Ihre Workflows nach setup-vp@v1 und ersetzen Sie die Vorkommen. Auf GitLab taucht die Version zweimal auf (einmal in der Include-URL und einmal in setup-ref); bei einem Upgrade müssen Sie beide Stellen manuell aktualisieren.

Fazit

Eine Vite+-Migration verläuft reibungslos, wenn Sie vp migrate als ersten Schritt und nicht als komplette Lösung betrachten. Lesen Sie den Plan, halten Sie Formatierungsänderungen von Logikänderungen getrennt, führen Sie die vier Prüfbefehle aus und pinnen Sie setup-vp in der CI, bevor Sie mergen. Legen Sie als Nächstes den Branch an, führen Sie vp migrate aus und arbeiten Sie die ausgegebenen Warnungen zu Hooks und Lint-Regeln durch.

FAQs

Was macht vp migrate bei einem Projekt, das bereits Vite+ verwendet?

Es aktualisiert lediglich die Toolchain. Abhängigkeiten und Paketmanager-Einstellungen werden in allen Workspace-Paketen auf die Versionen gebracht, die mit der ausführenden CLI ausgeliefert werden, und Imports werden finalisiert. Die Ersteinrichtung, etwa Git-Hooks, Editor- und Agent-Dateien sowie die Lint-Migration, wird übersprungen. Übergeben Sie --full, um diese Einrichtungsschritte ebenfalls auszuführen. Führen Sie zuvor vp upgrade aus, damit die globale CLI über die neuesten Migrationsregeln verfügt.

Sollte ich vp migrate aus den node_modules des Projekts ausführen?

Nein. Laut Vite+-Migrationsleitfaden sollte die Migration nicht mit dem node_modules/.bin/vp eines alten Projekts ausgeführt werden. Verwenden Sie ein global installiertes vp oder laden Sie das Ziel-Release mit npx --package=vite-plus@version vp migrate bzw. dem pnpm-dlx-Äquivalent. So wird die Ziel-CLI geladen, ohne die alten Abhängigkeiten des Projekts vorher zu ersetzen, und der Migrator kann weiterhin erkennen, von welcher Vitest-Version Sie ausgehen.

Welche Paketmanager unterstützt Vite+ nach der Migration?

Vite+ funktioniert mit pnpm, npm, Yarn und Bun. Der Paketmanager wird anhand von Dateien im Workspace-Root erkannt, etwa dem Feld packageManager und dem Lockfile; wird nichts gefunden, greift Vite+ auf pnpm zurück. vp install führt anschließend das passende Installationsverhalten für den erkannten Paketmanager aus, einschließlich der korrekten Lockfile-Flags.

Wie finde ich heraus, welche ESLint-Regeln bei der Migration weggefallen sind?

vp migrate meldet die nicht unterstützten ESLint-Regeln, die bei der Konvertierung nach Oxlint übersprungen werden. Diese Funktion wurde mit Vite+ 0.3.2 eingeführt, damit Sie prüfen können, welche Checks verloren gehen. Gehen Sie diese Liste vor dem Commit durch und ergänzen Sie benötigte Regeln, indem Sie ESLint als Projekt-Script beibehalten und über vp run ausführen.