Cómo migrar un proyecto existente a Vite+

Para migrar un proyecto existente a Vite+, ejecuta vp migrate en la raíz del proyecto o del workspace, en una rama nueva. Lee el plan que muestra antes de que se modifique ningún archivo y, a continuación, verifica el resultado con vp install, vp check, vp test y vp build (o vp pack si se trata de una librería) antes de actualizar la CI.

Trasladar un repositorio que funciona, con cinco configuraciones de herramientas independientes, a una nueva toolchain es el tipo de cambio que parece pequeño en el título de un PR y acaba ocupando un sprint entero. Normalmente los problemas empiezan cuando la parte automatizada ya ha terminado: en lo que convirtió y en lo que no.

Esta guía está pensada para proyectos que ya usan Vite, Vitest, ESLint y Prettier. Explica qué cambia vp migrate, qué deja en tus manos, qué revisar después y cómo actualizar GitHub Actions y GitLab CI. Si primero necesitas una visión general de Vite+ y sus comandos, empieza por Getting Started with Vite+. Vite+ 1.0 se publicó el 28 de septiembre de 2026 bajo licencia MIT.

¿Quién debería migrar a Vite+ y qué se obtiene?

La migración resulta adecuada para equipos que mantienen configuraciones separadas para Vite, Vitest, ESLint, Prettier y un bundler de librerías como tsup o tsdown. Tras la migración tendrás una sola dependencia vite-plus y un único vite.config.ts que contiene la configuración de desarrollo, tests, lint, formateo y empaquetado. tsup es una fuente de migración compatible, por lo que una librería TypeScript que se empaqueta con tsup también puede migrarse. Eso sí, cuenta con trabajo posterior. La guía de migración indica claramente que la mayoría de los proyectos necesitan algún ajuste manual una vez que el comando termina.

¿Qué necesitas antes de ejecutar vp migrate?

Ejecuta la migración a Vite+ en su propia rama, partiendo de un árbol de trabajo limpio. Así el diff contendrá únicamente los cambios de la migración y será fácil descartarlo.

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

Comprueba estos tres requisitos antes de empezar:

• Vite 7 o posterior. Los proyectos más antiguos deben actualizar Vite primero. What’s New in Vite 7 recoge los cambios de esa versión.
• Vitest 4 o posterior. Actualiza las suites más antiguas a la v4 antes de migrar.
• Node.js ^22.18.0 || ^24.11.0 || >=26.0.0, según la guía de actualización a Vitest 5.

Realiza primero cualquier actualización upstream y valídala; después conserva el lockfile y los paquetes instalados existentes. El migrador los lee para determinar desde qué versión de Vitest partes.

Ejecuta vp migrate y lee el plan

Ejecutar vp migrate sin argumentos migra el directorio actual. El comando muestra los cambios previstos antes de escribir ningún archivo. Pasa una ruta para migrar un proyecto ubicado en otro directorio.

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

El comando migrate acepta estos flags:

• --no-interactive se ejecuta sin solicitudes interactivas.
• --agent <name> / --no-agent controla si se configuran los archivos de instrucciones para agentes de programación.
• --editor <name> / --no-editor controla si se escribe la configuración del editor.
• --hooks / --no-hooks controla si se configuran los git hooks.

En un monorepo, la raíz del workspace es el único destino válido para vp migrate. Los lockfiles, catálogos y configuración del gestor de paquetes que reescribe pertenecen a todos los paquetes del workspace, así que ejecútalo una sola vez desde la raíz. No lo ejecutes paquete por paquete.

¿Qué convierte vp migrate y qué deja sin tocar?

vp migrate actualiza las dependencias, reescribe los imports, fusiona la configuración de las herramientas en vite.config.ts, actualiza los scripts de package.json y formatea los archivos que ha modificado. Deliberadamente, deja intactas las herramientas de git hooks existentes.

Los imports de los tests pasan de Vitest upstream a las re-exportaciones de vite-plus, que incluye Vitest 5. Las ampliaciones de tipos siguen apuntando al 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 conservas una herramienta de hooks, lint-staged también se mantiene, porque vp staged solo lee el bloque staged de vite.config.ts. El cambio tendrás que hacerlo manualmente:

import { defineConfig } from 'vite-plus'

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

En librerías con una versión de tsdown anterior a la 0.23 (o cuando no se puede detectar la versión instalada), la migración conserva los valores predeterminados antiguos. Añade deps.resolveDepSubpath: true al bloque pack si no lo has definido, y añade attw.profile: 'strict' si las comprobaciones de ATTW están activadas y no hay ningún perfil definido. Las reglas de migración recogen el conjunto completo de transformaciones.

¿Cómo se verifica el proyecto migrado?

Ejecuta vp install, vp check, vp test y vp build (o vp pack en el caso de una librería), y revisa cada resultado antes de hacer commit. Como la migración ejecuta el formateador sobre los archivos que modificó, revisa los cambios de formato por separado de los cambios de dependencias, configuración e imports. De lo contrario, un diff de reformateo puede ocultar cambios de lógica.

Lee el informe de revisión que genera la migración antes de hacer commit. Si utilizas suites en modo navegador, de cobertura o de benchmarks, ejecútalas también por separado.

¿Qué pasa si las reglas de lint o formato no se trasladan?

La migración convierte la flat config de ESLint a Oxlint y la configuración de Prettier a Oxfmt siempre que puede, pero no todas las reglas de ESLint tienen un equivalente en Oxlint. vp migrate enumera las reglas no compatibles que omite. Si una regla de la que dependes no se traslada, conserva la herramienta original como script del proyecto y ejecútala mediante vp run:

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

vp run lint:eslint

Esto solo funciona si el script de ESLint sobrevive a la migración, lo cual ocurre si rechazaste la conversión de ESLint/Prettier cuando se te preguntó o si tienes un .eslintrc heredado. En caso contrario, vuelve a añadir manualmente el paquete, la configuración y el script después de migrar. Ten en cuenta que vp test siempre ejecuta el comando de test integrado, mientras que vp run test ejecuta el script test que haya en package.json.

Si Node o el gestor de paquetes se resuelven a una versión incorrecta, ejecuta vp env doctor para diagnosticarlo.

¿Cómo se actualiza la CI para Vite+?

En la CI, la action de configuración de Vite+ sustituye los pasos independientes de Node, gestor de paquetes, instalación y caché, y los jobs invocan directamente los comandos vp. En GitHub Actions, setup-vp instala las dependencias salvo que definas 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

En GitLab, la guía de CI indica que incluyas la plantilla remota setup-vp.yml, extiendas .setup-vp y utilices una imagen que ya contenga 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

Fija setup-vp a un tag de versión exacto o a un SHA de commit en lugar de v1, porque VoidZero ya no actualiza ese tag. Busca setup-vp@v1 en tus workflows y sustitúyelo. En GitLab, la versión aparece dos veces (una en la URL del include y otra en setup-ref), y tendrás que actualizar ambas manualmente cuando cambies de versión.

Conclusión

Una migración a Vite+ transcurre sin problemas cuando tratas vp migrate como el primer paso y no como todo el trabajo. Lee su plan, separa los cambios de formato de los cambios de lógica, ejecuta los cuatro comandos de verificación y fija setup-vp en la CI antes de hacer merge. El siguiente paso: crea la rama, ejecuta vp migrate y revisa las advertencias que muestra sobre hooks y reglas de lint.

Preguntas frecuentes

¿Qué hace vp migrate en un proyecto que ya usa Vite+?

Solo actualiza la toolchain. Actualiza las dependencias y la configuración del gestor de paquetes en todos los paquetes del workspace a las versiones incluidas en la CLI que ejecuta la migración, y finaliza los imports. Omite la configuración inicial, como los git hooks, los archivos de editor y de agentes, y la migración de lint. Pasa --full para ejecutar también esas acciones de configuración. Ejecuta vp upgrade primero para que la CLI global tenga las reglas de migración más recientes.

¿Debo ejecutar vp migrate desde el node_modules del propio proyecto?

No. La guía de migración de Vite+ indica que no se debe ejecutar la migración con el node_modules/.bin/vp antiguo del proyecto. Usa un vp global, u obtén la versión de destino con npx --package=vite-plus@version vp migrate o su equivalente con pnpm dlx. Así se carga la CLI de destino sin sustituir antes las dependencias antiguas del proyecto, de modo que el migrador todavía puede detectar desde qué versión de Vitest partías.

¿Qué gestores de paquetes admite Vite+ después de la migración?

Vite+ funciona con pnpm, npm, Yarn y Bun. Detecta el gestor de paquetes a partir de archivos en la raíz del workspace, como el campo packageManager y el lockfile, y recurre a pnpm si no encuentra ninguno. A continuación, vp install aplica el comportamiento de instalación correspondiente al gestor detectado, incluidos los flags de lockfile adecuados.

¿Cómo puedo saber qué reglas de ESLint ha descartado la migración?

vp migrate informa de las reglas de ESLint no compatibles que omite durante la conversión a Oxlint. Esta función llegó en Vite+ 0.3.2 para que puedas revisar las comprobaciones que pierdes. Repasa esa lista antes de hacer commit y vuelve a añadir las reglas que necesites conservando ESLint como script del proyecto y ejecutándolo mediante vp run.