VuePress vs. VitePress: Wofür sollten Sie sich entscheiden?

Für nahezu jede neue Vue-Dokumentationsseite lautet die Antwort: VitePress.

Wer in letzter Zeit eine VuePress-1-Seite am Leben gehalten hat, kennt das Symptom: Man speichert eine Markdown-Datei und sucht sich dann erst einmal etwas anderes zu tun, während webpack neu baut. Genau diese Wartezeit macht den Kern dieses Vergleichs aus.

VitePress ist der Static-Site-Generator, den das Vue-Team offiziell empfiehlt. VuePress 1 ist deprecated, und VuePress 2 wird von der Community gepflegt und befindet sich weiterhin im Release-Candidate-Status. Greifen Sie nur dann zu VuePress 2, wenn Sie gezielt etwas benötigen, das dort nach wie vor besser gelöst ist – etwa eine eigene Plugin-/Theme-API oder das einfachere Austauschen von Komponenten. Und wenn Sie eine First-Party-Versionierung Ihrer Dokumentation brauchen, sollten Sie zu einem React-basierten Generator wie Docusaurus greifen.

Dieser Artikel begründet diese Empfehlung anhand der konkreten Unterschiede, die ein Docs-Projekt tatsächlich entscheiden: Projektdynamik, Geschwindigkeit des Dev-Loops, der Customization-Tradeoff und das, was VitePress ehrlicherweise noch nicht kann. Außerdem korrigiert er die veraltete Darstellung „VitePress ist Alpha“, die in älteren Vergleichen immer noch kursiert.

Was wird aktiv gepflegt – VuePress oder VitePress?

Die Projektdynamik ist der mit Abstand wichtigste Faktor dieser Entscheidung, und sie weist eindeutig in eine Richtung. VitePress knüpft dort an, wo VuePress aufgehört hat, und setzt dieselbe Markdown-zu-Docs-Idee auf Vue 3 und Vite um. Das Vue-Team kam zu dem Schluss, dass es nicht zwei Generatoren gleichzeitig weiterentwickeln kann, und entschied sich für VitePress als empfohlene Lösung – VuePress 1 wurde eingestellt und VuePress 2 an ein Community-Team übergeben.

Beim Reifegrad verhält es sich genau umgekehrt zu dem, was ältere Artikel behaupten. VitePress ist das stabile Projekt: npm führt weiterhin 1.6.4 als aktuelles Release, und das Changelog verortet die nächste Major-Linie im Alpha-Stadium bei 2.0.0-alpha.19. Das VuePress-Core-Repository beschreibt den eigenen Status nach wie vor als Release Candidate – VuePress 2 hat also nie ein finales Stable-Release erreicht. VitePress treibt außerdem die Dokumentationen von Vite, Rollup, Pinia, VueUse, Vitest, D3, UnoCSS, Iconify und der Vue.js-Website selbst an.

Developer Experience: Vite gegen webpack

Beim Dev-Loop setzt sich VitePress deutlich ab. VuePress 1 baute auf Vue 2 und webpack auf und veraltete dadurch schnell; VitePress läuft auf Vue 3 und Vite. Die offizielle Dokumentation beziffert die Spanne zwischen dem Speichern einer Datei und der sichtbaren Änderung auf unter 100 Millisekunden – ohne Page Reload und ohne Wartezeit für den Start des Dev-Servers. Das ist eine völlig andere Kategorie von Feedback-Schleife als ein webpack-Rebuild.

Auch die Output-Architektur ist relevant. In der Entwicklung läuft der Dev-Server auf Port 5173, sofern Sie ihn nicht umkonfigurieren. In Produktion ist die erste Seite, auf der ein Besucher landet, vorgerendertes statisches HTML: Es lädt schnell und lässt sich gut indexieren. VitePress hydratisiert die Seite anschließend zu einer Vue-Single-Page-App, sodass jede weitere Navigation im Browser stattfindet – so erklärt es der Blogpost zum 1.0-Release. Zusätzlich bringt VitePress eine lokale Volltextsuche mit, die nur eine Konfigurationsoption entfernt ist, sowie Shiki – denselben Syntaxhighlighter, den auch VS Code verwendet. Beides muss also nicht von Hand verdrahtet werden.

Konfiguration und Anpassung: der eigentliche Tradeoff

Hier liegt der ehrliche Zielkonflikt. VitePress hat eine einfachere Konfiguration und ein wirklich starkes Default-Theme, aber tiefgreifende Anpassungen bedeuten, Vue zu schreiben. VitePress hat bewusst kein eigenes Plugin-System: Die Anpassung wird über Custom Themes und Slots an Vue delegiert sowie über Config und Plugins an Vite. VuePress 2 behält eine breitere, eigenständige Plugin-/Theme-API und macht das Austauschen von Komponenten in der Konfiguration direkter – deshalb bleiben Teams mit stark angepassten VuePress-Seiten mitunter dabei.

Dieses Design hat praktische Kanten. Das Überschreiben von Scoped Styles innerhalb der Vue-Komponenten des Default-Themes erzwingt gelegentlich ein !important. Die Sidebar ist deutlich einfacher und unterstützt eine separate Sidebar pro Unterordner, allerdings schreiben Sie sie von Hand in themeConfig.sidebar: Eine neue Markdown-Datei erscheint erst, wenn Sie die Konfiguration anpassen oder ein Community-Plugin wie vitepress-sidebar einsetzen. Frontmatter lässt sich direkt im Markdown gut lesen, und Prev-/Next-Links werden aus der Sidebar abgeleitet, sofern Sie prev und next nicht selbst setzen – diese können auf jede beliebige Seite verweisen, ob in der Sidebar enthalten oder nicht.

Die VitePress-Sidebar-Konfiguration ist übersichtlich:

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

Verwenden Sie die pfadbasierte Objektform (sidebar: { '/guide/': [...] }), wenn Sie pro Abschnitt eine eigene Sidebar wünschen. Genau dieses Multi-Sidebar-Muster ist in VuePress aufwendiger umzusetzen.

Wann ist VitePress die falsche Wahl?

VitePress ist bewusst eng gefasst, und einige Lücken sind real. Es gibt keine First-Party-Versionierung der Dokumentation: Teams, die v1/v2/v3 parallel pflegen, halten separate Versionsordner vor und verdrahten die Sidebars manuell – der Hauptgrund, stattdessen zu Docusaurus zu greifen. Das Plugin-Ökosystem ist klein im Vergleich zu Docusaurus. Auch das Blog-Thema ist schwach ausgeprägt: kein integriertes Tag-System, kein RSS-Feed, keine Archivseite. Eine marketinglastige Website ist damit mehr Aufwand, als sie wert ist. Und Vue wird zwingend erforderlich, sobald Sie über Markdown und das Default-Theme hinausgehen.

Entscheiden Sie sich für VitePress – es sei denn, Sie benötigen ausdrücklich eine First-Party-Versionierung oder eine große Plugin-Bibliothek (Docusaurus-Terrain), oder Ihr Stack basiert auf React. In letzterem Fall passen Fumadocs, Nextra oder Docusaurus besser.

Migration von VuePress und das abschließende Fazit

Eine neue VitePress-Seite aufzusetzen, erfordert vier Befehle: npm add -D vitepress, anschließend npx vitepress init für den Setup-Assistenten, npm run docs:dev für den lokalen Server und npm run docs:build, um die statische Ausgabe nach .vitepress/dist zu schreiben. Die aktuelle offizielle Dokumentation verweist im Installationsbefehl standardmäßig auf die 2.0-Alpha-Linie (vitepress@next) und nennt Node.js 22 oder höher als Voraussetzung – das schlichte npm add -D vitepress liefert Ihnen also das stabile 1.x.

Die Migration von VuePress ist kein Drop-in-Ersatz. Ihr Markdown, das Frontmatter und die gemeinsam genutzten Markdown-Erweiterungen lassen sich sauber übernehmen; Config-Schema, Theme und Layout müssen überarbeitet werden, und für eigene VuePress-Plugins braucht es VitePress-Äquivalente. Seiten mit dem Default-Theme migrieren am leichtesten.

Die Entscheidungsregel: Für eine neue Vue-Dokumentationsseite wählen Sie VitePress – ohne Wenn und Aber. Wenn Sie eine VuePress-Seite mit Default-Theme betreiben, migrieren Sie zu VitePress. Wenn Sie First-Party-Versionierung oder eine umfangreiche Plugin-Bibliothek benötigen, ziehen Sie Docusaurus in Betracht. Und wenn Ihr Stack auf React basiert, beginnen Sie gleich mit einem React-basierten Generator. Installieren Sie VitePress, führen Sie npx vitepress init aus – und Sie haben eine funktionierende Docs-Seite, bevor Sie die Config-Referenz zu Ende gelesen haben.

FAQs

Ist VuePress deprecated?

VuePress 1 ist deprecated und befindet sich im Maintenance-Modus, während VuePress 2 an ein Community-Team übergeben wurde und ein Release Candidate bleibt, der nie eine finale stabile Version ausgeliefert hat. Das Vue-Team kam zu dem Schluss, dass die parallele Pflege zweier Generatoren nicht tragfähig ist, und empfiehlt nun VitePress als seinen wichtigsten Static-Site-Generator. Auf npm verweist der 'latest'-Tag von VuePress Core weiterhin auf die 1.x-Linie – ein weiterer Beleg dafür, dass 2.0 den RC-Status nie verlassen hat.

Kann VitePress die Sidebar automatisch aus meiner Ordnerstruktur generieren?

Nein. VitePress generiert die Sidebar standardmäßig nicht automatisch. Eine neue Markdown-Datei erscheint erst, wenn Sie die Sidebar manuell in Ihrer Konfigurationsdatei anpassen oder ein Community-Plugin wie vitepress-sidebar installieren. VitePress unterstützt zwar mehrere pfadbasierte Sidebars, sodass Sie pro Unterordner eine eigene Sidebar definieren können, die Zuordnung erfolgt jedoch explizit und wird nicht aus dem Verzeichnisbaum abgeleitet.

Unterstützt VitePress die Versionierung von Dokumentation wie Docusaurus?

Nein. VitePress verfügt über keine integrierte First-Party-Versionierung. Teams, die mehrere Dokumentationsversionen parallel pflegen, halten separate Versionsordner vor und verdrahten ihre Sidebars manuell. Wenn versionierte Dokumentation mit Dropdown-Umschaltung eine harte Anforderung ist, ist Docusaurus die stärkere Wahl, denn die First-Party-Versionierung gehört dort zu den Kernfunktionen. Das ist der mit Abstand häufigste Grund, einen React-basierten Generator statt VitePress zu wählen.

Warum erfordert VitePress für tiefgreifende Anpassungen das Schreiben von Vue-Komponenten?

VitePress hat bewusst kein eigenes Plugin-System. Statt einer eigenständigen Plugin-API wird die Anpassung über Custom Themes und Slots an Vue sowie über Config und Plugin-Ökosystem an Vite delegiert. Das hält den Core minimal, bedeutet aber, dass das Überschreiben von Aussehen oder Verhalten des Default-Themes das Schreiben von Vue-Komponenten erfordert – und gelegentlich, Scoped-Style-Overrides mit !important zu erzwingen – statt lediglich Konfigurationsoptionen umzuschalten.