Como migrar um projeto existente para o Vite+

Para migrar um projeto existente para o Vite+, execute vp migrate na raiz do projeto ou do workspace, em uma branch nova. Leia o plano que ele exibe antes de qualquer arquivo ser alterado e, em seguida, confirme o resultado com vp install, vp check, vp test e vp build (ou vp pack, no caso de uma biblioteca) antes de atualizar o CI.

Migrar um repositório funcional com cinco configurações de ferramentas separadas para um novo toolchain é o tipo de mudança que parece pequena no título do PR e acaba consumindo uma sprint inteira. Normalmente, os problemas começam depois que a parte automatizada termina, no que ela converteu e no que deixou de converter.

Este guia é voltado para projetos que já usam Vite, Vitest, ESLint e Prettier. Ele aborda o que o vp migrate altera, o que ele deixa por sua conta, o que verificar depois e como atualizar o GitHub Actions e o GitLab CI. Se você precisa primeiro de uma visão geral do Vite+ e de seus comandos, comece por Getting Started with Vite+. O Vite+ 1.0 foi lançado em 28 de setembro de 2026 sob a licença MIT.

Quem deve migrar para o Vite+ e o que se ganha com isso?

A migração é indicada para equipes que mantêm configurações separadas para Vite, Vitest, ESLint, Prettier e um bundler de bibliotecas como tsup ou tsdown. Após a migração, você passa a ter uma única dependência vite-plus e um único vite.config.ts com as configurações de dev, testes, lint, formatação e empacotamento. O tsup é uma origem de migração suportada, então uma biblioteca TypeScript empacotada com tsup também pode ser migrada. Ainda assim, espere algum trabalho adicional. O guia de migração afirma claramente que a maioria dos projetos precisa de algum ajuste manual depois que o comando termina.

O que é necessário antes de executar o vp migrate?

Execute a migração para o Vite+ em uma branch dedicada, partindo de uma working tree limpa. Assim, o diff contém apenas as mudanças da migração e fica fácil descartá-lo.

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

Verifique estes três pontos antes de começar:

• Vite 7 ou superior. Projetos mais antigos precisam atualizar o Vite primeiro. What’s New in Vite 7 aborda as mudanças dessa versão.
• Vitest 4 ou superior. Atualize suítes mais antigas para a v4 antes de migrar.
• Node.js ^22.18.0 || ^24.11.0 || >=26.0.0, conforme o guia de upgrade para o Vitest 5.

Faça primeiro os upgrades upstream necessários e valide-os; depois, mantenha o lockfile e os pacotes instalados existentes. O migrador os lê para identificar a versão do Vitest de que você partiu.

Execute o vp migrate e leia o plano

Executar vp migrate sem argumentos migra o diretório atual. Ele mostra as mudanças planejadas antes de gravar qualquer arquivo. Informe um caminho para migrar um projeto em outro diretório.

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

O comando migrate aceita as seguintes flags:

• --no-interactive executa sem prompts.
• --agent <name> / --no-agent controla se os arquivos de instruções para agentes de código serão configurados.
• --editor <name> / --no-editor controla se a configuração do editor será gravada.
• --hooks / --no-hooks controla se os git hooks serão configurados.

Em um monorepo, a raiz do workspace é o único alvo válido para o vp migrate. Os lockfiles, catálogos e configurações do gerenciador de pacotes que ele reescreve pertencem a todos os pacotes do workspace, então execute-o uma única vez a partir da raiz. Não o execute pacote por pacote.

O que o vp migrate converte e o que ele deixa intacto?

O vp migrate atualiza dependências, reescreve imports, mescla a configuração das ferramentas no vite.config.ts, atualiza os scripts do package.json e formata os arquivos que alterou. Ele deixa intencionalmente intactas as ferramentas de git hooks existentes.

Os imports de testes deixam de apontar para o Vitest upstream e passam a usar os re-exports do vite-plus, que inclui o Vitest 5. As type augmentations continuam apontando para o 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
}

Se você mantiver uma ferramenta de hooks, o lint-staged também permanece, porque o vp staged lê apenas o bloco staged do vite.config.ts. A troca para ele é feita manualmente:

import { defineConfig } from 'vite-plus'

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

Para bibliotecas com tsdown anterior à 0.23 (ou quando a versão instalada não pode ser encontrada), a migração mantém os padrões antigos. Ela adiciona deps.resolveDepSubpath: true ao bloco pack se você não o tiver definido e adiciona attw.profile: 'strict' se as verificações do ATTW estiverem ativadas e nenhum profile estiver definido. As regras de migração listam o conjunto completo de transformações.

Como verificar o projeto migrado?

Execute vp install, vp check, vp test e vp build (ou vp pack, no caso de uma biblioteca) e revise cada resultado antes de fazer o commit. Como a migração executa o formatador nos arquivos que alterou, revise as mudanças de formatação separadamente das mudanças de dependências, configuração e imports. Caso contrário, um diff de reformatação pode esconder mudanças de lógica.

Leia o relatório de revisão gerado pela migração antes de fazer o commit. Se você tiver suítes em browser mode, de cobertura ou de benchmark, execute-as separadamente também.

E se as regras de lint ou formatação não forem migradas?

A migração converte a flat config do ESLint para o Oxlint e a configuração do Prettier para o Oxfmt sempre que possível, mas nem toda regra do ESLint tem um equivalente no Oxlint. O vp migrate lista as regras não suportadas que ele ignora. Se uma regra da qual você depende não for migrada, mantenha a ferramenta original como um script do projeto e execute-a por meio do vp run:

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

vp run lint:eslint

Isso só funciona se o script do ESLint sobreviver à migração, o que acontece caso você tenha recusado o prompt de conversão do ESLint/Prettier ou tenha um .eslintrc legado. Caso contrário, adicione novamente o pacote, a configuração e o script manualmente após a migração. Observe que o vp test sempre executa o comando de testes nativo, enquanto o vp run test executa qualquer script test que esteja no package.json.

Se o Node ou o gerenciador de pacotes for resolvido para a versão errada, execute vp env doctor para diagnosticar o problema.

Como atualizar o CI para o Vite+?

No CI, a action de setup do Vite+ substitui os steps separados de Node, gerenciador de pacotes, instalação e cache, e os jobs chamam os comandos vp diretamente. No GitHub Actions, o setup-vp instala as dependências, a menos que você defina 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

No GitLab, o guia de CI orienta a incluir o template remoto setup-vp.yml, estender .setup-vp e usar uma imagem que já contenha o 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

Fixe o setup-vp em uma tag de release exata ou no SHA de um commit em vez de v1, pois a VoidZero não atualiza mais essa tag. Procure por setup-vp@v1 nos seus workflows e substitua. No GitLab, a versão aparece duas vezes (uma na URL do include e outra em setup-ref), e você precisa atualizar ambas manualmente ao fazer upgrade.

Conclusão

Uma migração para o Vite+ corre bem quando você trata o vp migrate como o primeiro passo, e não como o trabalho inteiro. Leia o plano gerado, mantenha as mudanças de formatação separadas das mudanças de lógica, execute os quatro comandos de verificação e fixe a versão do setup-vp no CI antes de fazer o merge. Como próximo passo, crie a branch, execute o vp migrate e analise os avisos que ele exibe sobre hooks e regras de lint.

Perguntas frequentes

O que o vp migrate faz em um projeto que já usa o Vite+?

Ele apenas atualiza o toolchain. Ele atualiza as dependências e as configurações do gerenciador de pacotes em todos os pacotes do workspace para as versões incluídas na CLI que está executando a migração e finaliza os imports. Ele ignora a configuração inicial, como git hooks, arquivos de editor e de agentes e a migração de lint. Passe --full para executar também essas ações de configuração. Execute vp upgrade antes para que a CLI global tenha as regras de migração mais recentes.

Devo executar o vp migrate a partir do node_modules do próprio projeto?

Não. O guia de migração do Vite+ recomenda não executar a migração com o node_modules/.bin/vp antigo do projeto. Use um vp global ou obtenha a release desejada com npx --package=vite-plus@version vp migrate ou o equivalente com pnpm dlx. Isso carrega a CLI desejada sem substituir antes as dependências antigas do projeto, de modo que o migrador ainda consiga detectar a versão do Vitest de que você partiu.

Quais gerenciadores de pacotes o Vite+ suporta após a migração?

O Vite+ funciona com pnpm, npm, Yarn e Bun. Ele detecta o gerenciador de pacotes a partir de arquivos na raiz do workspace, como o campo packageManager e o lockfile, e recorre ao pnpm se não encontrar nenhum. Em seguida, o vp install executa o comportamento de instalação correspondente ao gerenciador detectado, incluindo as flags corretas de lockfile.

Como descobrir quais regras do ESLint a migração descartou?

O vp migrate informa as regras do ESLint não suportadas que ele ignora durante a conversão para o Oxlint. Esse recurso chegou no Vite+ 0.3.2 para que você possa revisar as verificações que perderá. Analise essa lista antes de fazer o commit e, em seguida, adicione novamente as regras de que precisar mantendo o ESLint como um script do projeto e executando-o por meio do vp run.