VuePress vs VitePress: Qual Você Deve Escolher?

Para praticamente todo novo site de documentação Vue, escolha o VitePress.

Se você manteve um site VuePress 1 vivo recentemente, conhece bem o sinal: você salva um arquivo Markdown e então vai procurar outra coisa para fazer enquanto o webpack reconstrói tudo. Essa lacuna é a essência do que esta comparação aborda.

O VitePress é o gerador de sites estáticos oficialmente recomendado pela equipe do Vue, o VuePress 1 está descontinuado, e o VuePress 2 é mantido pela comunidade e ainda está em release candidate. Escolha o VuePress 2 apenas quando você precisar especificamente de algo que ele ainda faz melhor, como uma API de plugins/temas customizada ou substituição de componentes mais fácil, e opte por um gerador baseado em React como o Docusaurus se você precisar de versionamento de documentação nativo.

Este artigo justifica essa recomendação com as diferenças concretas que realmente decidem um projeto de documentação: momentum do projeto, velocidade do ciclo de desenvolvimento, o trade-off de customização e o que o VitePress genuinamente ainda não consegue fazer. Também corrige a narrativa desatualizada de que “o VitePress é alpha”, que você ainda encontra em comparações mais antigas.

Qual é mantido ativamente, VuePress ou VitePress?

O momentum do projeto é o fator mais determinante nesta decisão, e ele aponta para uma única direção. O VitePress retoma de onde o VuePress parou, executando a mesma ideia de Markdown-para-documentação sobre Vue 3 e Vite. A equipe do Vue concluiu que não conseguiria manter dois geradores ao mesmo tempo e definiu o VitePress como o recomendado, descontinuando o VuePress 1 e passando o VuePress 2 para uma equipe da comunidade.

O panorama de maturidade é o inverso do que artigos mais antigos afirmam. O VitePress é o estável: o npm ainda lista o 1.6.4 como seu release mais recente, e o changelog coloca a próxima linha major em alpha, no 2.0.0-alpha.19. O repositório core do VuePress ainda descreve seu próprio status como release candidate, então o VuePress 2 nunca chegou a um release final estável. O VitePress também sustenta a documentação do Vite, Rollup, Pinia, VueUse, Vitest, D3, UnoCSS, Iconify e do próprio site do Vue.js.

Experiência de desenvolvimento: Vite versus webpack

O ciclo de desenvolvimento é onde o VitePress se destaca. O VuePress 1 foi construído sobre Vue 2 e webpack, o que envelheceu rapidamente; o VitePress roda sobre Vue 3 e Vite. A documentação oficial coloca o intervalo entre salvar um arquivo e ver a mudança na tela em menos de 100 milissegundos, sem recarregamento de página e sem espera para o dev server inicializar. Isso é uma classe completamente diferente de ciclo de feedback comparado a um rebuild do webpack.

A arquitetura de saída também importa. Em desenvolvimento, o dev server roda na porta 5173 a menos que você o direcione para outro lugar. Em produção, a primeira página em que um visitante chega é HTML estático pré-renderizado, que carrega rapidamente e é bem indexado; o VitePress então a hidrata em uma single-page app Vue, de modo que toda navegação posterior acontece no navegador, como o post de lançamento do 1.0 explica. O VitePress também traz busca local de texto completo embutida, a uma opção de configuração de distância, e o Shiki, o mesmo realçador de sintaxe que o VS Code usa, então nenhum dos dois precisa ser configurado manualmente.

Configuração e customização: o trade-off real

Aqui está a tensão honesta. O VitePress tem uma configuração mais simples e um tema padrão genuinamente forte, mas customização profunda significa escrever Vue. O VitePress não possui um sistema de plugins próprio, e isso é intencional: a customização é delegada ao Vue via temas customizados e slots, e ao Vite via sua configuração e plugins. O VuePress 2 mantém uma API de plugins/temas mais ampla e customizada e torna a substituição de componentes na configuração mais direta, e é por isso que equipes profundamente envolvidas com um site VuePress customizado às vezes permanecem onde estão.

Esse design tem arestas práticas. Sobrescrever estilos com escopo dentro dos componentes Vue do tema padrão ocasionalmente força um !important. A sidebar é muito mais simples e suporta uma sidebar separada por subpasta, mas você a escreve manualmente em themeConfig.sidebar: um novo arquivo Markdown não vai aparecer até você editar a configuração ou adicionar um plugin da comunidade como o vitepress-sidebar. O frontmatter é fácil de ler diretamente dentro do Markdown, e os links prev/next são inferidos da sidebar a menos que você defina prev e next você mesmo, os quais podem apontar para qualquer página, esteja ela na sidebar ou não.

A configuração da sidebar do VitePress é limpa:

// .vitepress/config.ts
export default {
  themeConfig: {
    sidebar: [
      {
        text: 'Guide',
        collapsed: true,
        items: [
          { text: 'Introduction', link: '/guide/' },
          { text: 'Getting Started', link: '/guide/getting-started' },
        ],
      },
    ],
  },
}

Use a forma de objeto indexada por caminho (sidebar: { '/guide/': [...] }) quando quiser uma sidebar distinta por seção. Esse é o padrão de múltiplas sidebars que o VuePress torna mais difícil.

Quando o VitePress é a escolha errada?

O VitePress tem escopo deliberadamente limitado, e algumas lacunas são reais. Ele não tem versionamento de documentação nativo: equipes que mantêm v1/v2/v3 simultaneamente mantêm pastas de versão separadas e configuram as sidebars manualmente, o que é a principal razão para escolher o Docusaurus em vez dele. Seu ecossistema de plugins é pequeno ao lado do Docusaurus. Sua capacidade de blog é fraca: sem sistema de tags embutido, feed RSS ou página de arquivo, então um site voltado a marketing dá mais trabalho do que compensa. E ele exige Vue no momento em que você vai além do Markdown e do tema padrão.

Escolha o VitePress a menos que você precise especificamente de versionamento nativo ou de uma grande biblioteca de plugins, que é território do Docusaurus, ou sua stack seja React, caso em que Fumadocs, Nextra ou Docusaurus se encaixam melhor.

Migrando do VuePress, e o veredito final

Criar a estrutura de um novo site VitePress são quatro comandos: npm add -D vitepress, então npx vitepress init para rodar o assistente de configuração, npm run docs:dev para o servidor local, e npm run docs:build para emitir a saída estática em .vitepress/dist. A documentação oficial atual usa como padrão em seu comando de instalação a linha 2.0-alpha (vitepress@next) e lista Node.js 22 ou superior como pré-requisito, então o simples npm add -D vitepress é o que te dá a versão estável 1.x.

A migração do VuePress não é um drop-in. Seu Markdown, frontmatter e extensões Markdown compartilhadas são transferidos sem problemas; o schema de configuração, o tema e o layout precisam ser refeitos, e quaisquer plugins customizados do VuePress precisam de equivalentes no VitePress. Sites com tema padrão migram com mais facilidade.

A regra de decisão: para um novo site de documentação Vue, escolha o VitePress e não olhe para trás. Se você está em um site VuePress com tema padrão, migre para o VitePress. Se você precisa de versionamento nativo ou de uma biblioteca de plugins robusta, considere o Docusaurus. E se sua stack é React, comece com um gerador baseado em React. Instale o VitePress, execute npx vitepress init, e você terá um site de documentação funcionando antes de terminar de ler a referência de configuração.

Perguntas Frequentes

O VuePress está descontinuado?

O VuePress 1 está descontinuado e em modo de manutenção, enquanto o VuePress 2 foi entregue a uma equipe da comunidade e permanece como um release candidate que nunca lançou uma versão final estável. A equipe do Vue decidiu que manter dois geradores em paralelo não era sustentável e agora recomenda o VitePress como seu principal gerador de sites estáticos. No npm, a tag 'latest' do core do VuePress ainda resolve para a linha 1.x, reforçando que o 2.0 nunca saiu de RC.

O VitePress consegue gerar a sidebar automaticamente a partir da minha estrutura de pastas?

Não. O VitePress não gera a sidebar automaticamente por padrão. Um novo arquivo Markdown não vai aparecer até você editar manualmente a sidebar no seu arquivo de configuração ou instalar um plugin da comunidade como o vitepress-sidebar. O VitePress suporta múltiplas sidebars indexadas por caminho, então você pode definir uma sidebar distinta por subpasta, mas o mapeamento é explícito em vez de derivado da árvore de diretórios.

O VitePress suporta versionamento de documentação como o Docusaurus?

Não. O VitePress não tem funcionalidade nativa de versionamento embutida. Equipes que mantêm várias versões de documentação simultaneamente mantêm pastas de versão separadas e configuram suas sidebars manualmente. Se documentação versionada com troca via dropdown é um requisito rígido, o Docusaurus é a escolha mais forte, já que o versionamento nativo é uma de suas funcionalidades principais. Essa é a razão mais comum para escolher um gerador baseado em React em vez do VitePress.

Por que o VitePress exige escrever componentes Vue para customização profunda?

O VitePress não possui um sistema de plugins próprio, e isso é intencional. Em vez de uma API de plugins customizada, a customização é delegada ao Vue por meio de temas customizados e slots, e ao Vite por meio de sua configuração e ecossistema de plugins. Isso mantém o core minimalista, mas significa que sobrescrever a aparência ou o comportamento do tema padrão envolve escrever componentes Vue e ocasionalmente forçar sobrescritas de estilos com escopo usando !important, em vez de simplesmente alternar opções de configuração.