Comment migrer un projet existant vers Vite+

Pour migrer un projet existant vers Vite+, exécutez vp migrate à la racine du projet ou du workspace, sur une nouvelle branche. Lisez le plan affiché avant toute modification de fichier, puis validez le résultat avec vp install, vp check, vp test et vp build (ou vp pack pour une bibliothèque) avant de mettre à jour votre CI.

Faire passer un dépôt fonctionnel, doté de cinq configurations d’outils distinctes, sur une nouvelle chaîne d’outils est le genre de changement qui paraît anodin dans le titre d’une PR et finit par occuper un sprint entier. Les difficultés commencent généralement une fois la partie automatisée terminée : elles tiennent à ce qu’elle a converti, et à ce qu’elle n’a pas converti.

Ce guide s’adresse aux projets qui utilisent déjà Vite, Vitest, ESLint et Prettier. Il explique ce que vp migrate modifie, ce qu’il vous laisse à faire, ce qu’il faut vérifier ensuite, et comment mettre à jour GitHub Actions et GitLab CI. Si vous avez d’abord besoin d’une présentation de Vite+ et de ses commandes, commencez par Getting Started with Vite+. Vite+ 1.0 est sorti le 28 septembre 2026 sous licence MIT.

Qui devrait migrer vers Vite+ et qu’y gagne-t-on ?

La migration convient aux équipes qui maintiennent des configurations séparées pour Vite, Vitest, ESLint, Prettier et un bundler de bibliothèques comme tsup ou tsdown. Après la migration, vous disposez d’une seule dépendance vite-plus et d’un seul vite.config.ts regroupant les paramètres de dev, de test, de lint, de formatage et de pack. tsup fait partie des sources de migration prises en charge : une bibliothèque TypeScript bundlée avec tsup peut donc elle aussi être migrée. Prévoyez toutefois du travail complémentaire. Le guide de migration indique clairement que la plupart des projets nécessitent quelques ajustements manuels une fois la commande terminée.

De quoi avez-vous besoin avant d’exécuter vp migrate ?

Effectuez la migration vers Vite+ sur une branche dédiée, à partir d’un arbre de travail propre. Ainsi, le diff ne contient que les changements liés à la migration et peut être facilement abandonné.

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

Vérifiez ces trois points avant de commencer :

• Vite 7 ou version ultérieure. Les projets plus anciens doivent d’abord mettre à jour Vite. What’s New in Vite 7 présente les changements de cette version.
• Vitest 4 ou version ultérieure. Mettez à jour les suites plus anciennes vers la v4 avant de migrer.
• Node.js ^22.18.0 || ^24.11.0 || >=26.0.0, selon le guide de mise à niveau vers Vitest 5.

Effectuez d’abord les éventuelles mises à jour en amont et validez-les, puis conservez le lockfile et les paquets installés existants. Le migrateur s’en sert pour déterminer la version de Vitest de départ.

Exécuter vp migrate et lire le plan

Sans argument, vp migrate migre le répertoire courant. La commande affiche les changements prévus avant d’écrire le moindre fichier. Passez un chemin pour migrer un projet situé dans un autre répertoire.

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

La commande migrate accepte les options suivantes :

• --no-interactive s’exécute sans invite.
• --agent <name> / --no-agent détermine si les fichiers d’instructions pour agents de code sont configurés.
• --editor <name> / --no-editor détermine si la configuration de l’éditeur est générée.
• --hooks / --no-hooks détermine si les hooks git sont configurés.

Dans un monorepo, la racine du workspace est la seule cible valide pour vp migrate. Les lockfiles, catalogues et paramètres du gestionnaire de paquets qu’il réécrit concernent tous les packages du workspace : exécutez-le donc une seule fois depuis la racine, et non package par package.

Que convertit vp migrate et que laisse-t-il de côté ?

vp migrate met à jour les dépendances, réécrit les imports, fusionne la configuration des outils dans vite.config.ts, met à jour les scripts de package.json et formate les fichiers modifiés. Il laisse délibérément intacts les outils de hooks git existants.

Les imports de test passent de Vitest upstream aux réexportations de vite-plus, qui embarque Vitest 5. Les augmentations de types continuent de cibler le paquet vitest upstream :

// 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
}

Si vous conservez un outil de hooks, lint-staged est également conservé, car vp staged ne lit que le bloc staged de vite.config.ts. La bascule se fait manuellement :

import { defineConfig } from 'vite-plus'

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

Pour les bibliothèques utilisant une version de tsdown antérieure à 0.23 (ou lorsque la version installée est introuvable), la migration conserve les anciens comportements par défaut. Elle ajoute deps.resolveDepSubpath: true au bloc pack si vous ne l’avez pas défini, ainsi que attw.profile: 'strict' si les vérifications ATTW sont activées sans profil défini. Les règles de migration détaillent l’ensemble des transformations.

Comment vérifier le projet migré ?

Exécutez vp install, vp check, vp test et vp build (ou vp pack pour une bibliothèque), et examinez chaque résultat avant de committer. Comme la migration applique le formateur aux fichiers modifiés, relisez les changements de formatage séparément des changements de dépendances, de configuration et d’imports. Sinon, un diff de reformatage risque de masquer des modifications de logique.

Lisez le rapport de revue généré par la migration avant de committer. Si vous avez des suites en mode navigateur, de couverture ou de benchmark, exécutez-les également séparément.

Que faire si certaines règles de lint ou de formatage ne sont pas reprises ?

La migration convertit, dans la mesure du possible, la flat config ESLint vers Oxlint et la configuration Prettier vers Oxfmt, mais toutes les règles ESLint n’ont pas d’équivalent Oxlint. vp migrate liste les règles non prises en charge qu’il ignore. Si une règle dont vous dépendez n’est pas reprise, conservez l’outil d’origine sous forme de script de projet et exécutez-le via vp run :

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

vp run lint:eslint

Cela ne fonctionne que si le script ESLint survit à la migration, c’est-à-dire si vous avez refusé la conversion ESLint/Prettier proposée ou si vous utilisez un .eslintrc legacy. Dans le cas contraire, réintégrez vous-même le paquet, la configuration et le script après la migration. Notez que vp test exécute toujours la commande de test intégrée, tandis que vp run test exécute le script test défini dans package.json.

Si Node ou le gestionnaire de paquets ne se résout pas vers la bonne version, lancez vp env doctor pour diagnostiquer le problème.

Comment mettre à jour la CI pour Vite+ ?

En CI, l’action de configuration Vite+ remplace les étapes distinctes de Node, du gestionnaire de paquets, d’installation et de cache, et les jobs appellent directement les commandes vp. Sur GitHub Actions, setup-vp installe les dépendances, sauf si vous définissez 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

Sur GitLab, le guide CI indique d’inclure le template distant setup-vp.yml, d’étendre .setup-vp et d’utiliser une image contenant déjà 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

Épinglez setup-vp sur un tag de release exact ou un SHA de commit plutôt que sur v1, car VoidZero ne met plus ce tag à jour. Recherchez setup-vp@v1 dans vos workflows et remplacez-le. Sur GitLab, la version apparaît deux fois (une fois dans l’URL de l’include et une fois dans setup-ref) : vous devez mettre à jour les deux manuellement lors d’une montée de version.

Conclusion

Une migration vers Vite+ se déroule sans accroc si vous considérez vp migrate comme la première étape et non comme l’intégralité du travail. Lisez son plan, séparez les changements de formatage des changements de logique, exécutez les quatre commandes de vérification et épinglez setup-vp dans votre CI avant de merger. Prochaine étape : créez la branche, lancez vp migrate et passez en revue les avertissements qu’il affiche concernant les hooks et les règles de lint.

FAQ

Que fait vp migrate sur un projet qui utilise déjà Vite+ ?

Il se contente de mettre à niveau la chaîne d'outils. Il met à jour les dépendances et les paramètres du gestionnaire de paquets de tous les packages du workspace vers les versions embarquées par la CLI qui exécute la migration, et finalise les imports. Il ignore la configuration initiale, comme les hooks git, les fichiers d'éditeur et d'agent, ainsi que la migration du lint. Passez --full pour exécuter également ces actions de configuration. Lancez d'abord vp upgrade afin que la CLI globale dispose des règles de migration les plus récentes.

Dois-je exécuter vp migrate depuis le node_modules du projet ?

Non. Le guide de migration de Vite+ déconseille de lancer la migration avec le node_modules/.bin/vp d'un ancien projet. Utilisez un vp global, ou récupérez la release cible avec npx --package=vite-plus@version vp migrate ou son équivalent pnpm dlx. Cela charge la CLI cible sans remplacer au préalable les anciennes dépendances du projet, ce qui permet au migrateur de détecter la version de Vitest de départ.

Quels gestionnaires de paquets Vite+ prend-il en charge après la migration ?

Vite+ fonctionne avec pnpm, npm, Yarn et Bun. Il détecte le gestionnaire de paquets à partir des fichiers présents à la racine du workspace, comme le champ packageManager et le lockfile, et se rabat sur pnpm s'il n'en trouve aucun. vp install applique ensuite le comportement d'installation correspondant au gestionnaire détecté, y compris les bonnes options de lockfile.

Comment savoir quelles règles ESLint la migration a abandonnées ?

vp migrate signale les règles ESLint non prises en charge qu'il ignore lors de la conversion vers Oxlint. Cette fonctionnalité, arrivée avec Vite+ 0.3.2, vous permet de passer en revue les vérifications perdues. Parcourez cette liste avant de committer, puis réintégrez les règles dont vous avez besoin en conservant ESLint sous forme de script de projet exécuté via vp run.