VuePress と VitePress、どちらを選ぶべきか

新規の Vue ドキュメントサイトなら、ほぼすべてのケースで VitePress を選ぶべきです。

最近まで VuePress 1 のサイトを維持してきた方なら、その兆候をご存じでしょう。Markdown ファイルを保存し、webpack のリビルドが終わるまで別の作業を探しに行く——あの待ち時間こそが、この比較の要点のほとんどを占めています。

VitePress は Vue チームが公式に推奨する静的サイトジェネレーターであり、VuePress 1 は非推奨、VuePress 2 はコミュニティによって保守されている、いまだリリース候補（RC）段階のプロジェクトです。VuePress 2 を選ぶべきなのは、独自のプラグイン/テーマ API やコンポーネント差し替えの容易さなど、VuePress 2 のほうが依然として優れている点が明確に必要な場合だけです。また、ファーストパーティのドキュメントバージョニングが必要なら、Docusaurus のような React ベースのジェネレーターを検討してください。

本記事では、ドキュメントプロジェクトの選定を実際に左右する具体的な差異——プロジェクトの勢い、開発ループの速度、カスタマイズ性とのトレードオフ、そして VitePress が本当にまだできないこと——をもとに、この判断を裏づけます。あわせて、古い比較記事にいまだ残る「VitePress はアルファ版」という時代遅れの前提も訂正します。

VuePress と VitePress、活発に保守されているのはどちらか

プロジェクトの勢いはこの判断における最大の要素であり、その答えは一方向を指しています。VitePress は VuePress が残した地点を引き継ぎ、同じ「Markdown からドキュメントへ」という発想を Vue 3 と Vite の上で実現しています。Vue チームは 2 つのジェネレーターを同時に維持し続けることはできないと結論づけ、推奨ジェネレーターとして VitePress を選び、VuePress 1 を引退させ、VuePress 2 をコミュニティチームに引き継ぎました。

成熟度の構図は、古い記事が主張しているものとは逆です。安定しているのは VitePress のほうです。npm では依然として 1.6.4 が最新リリースとして掲載されており、チェンジログでは次のメジャー系列は 2.0.0-alpha.19 としてアルファ段階に位置づけられています。VuePress のコアリポジトリは自らのステータスをいまだリリース候補と記述しており、VuePress 2 は最終安定版に到達していません。また、VitePress は Vite、Rollup、Pinia、VueUse、Vitest、D3、UnoCSS、Iconify、そして Vue.js 公式サイト自体のドキュメントを支えています。

開発体験：Vite と webpack

VitePress が真価を発揮するのは開発ループです。VuePress 1 は Vue 2 と webpack の上に構築されており、すぐに古さが目立つようになりました。一方 VitePress は Vue 3 と Vite で動作します。公式ドキュメントによれば、ファイルを保存してから画面に変更が反映されるまでの遅延は 100 ミリ秒未満で、ページのリロードも、開発サーバーの起動待ちも不要です。webpack のリビルドとは、フィードバックループのクラスが根本的に異なります。

出力アーキテクチャも重要です。開発時には、明示的に指定しない限り開発サーバーはポート 5173 で動作します。本番環境では、訪問者が最初に着地するページは事前レンダリングされた静的 HTML であり、高速に読み込まれ、インデックスもされやすくなっています。その後 VitePress はそれを Vue のシングルページアプリケーションとしてハイドレートするため、以降のナビゲーションはすべてブラウザー内で完結します（1.0 リリース記事で解説されているとおりです）。さらに VitePress は、設定オプション 1 つで有効化できるローカル全文検索と、VS Code と同じシンタックスハイライターである Shiki を標準で内蔵しているため、いずれも手作業で組み込む必要がありません。

設定とカスタマイズ：本当のトレードオフ

ここに正直な緊張関係があります。VitePress は設定がシンプルで、デフォルトテーマも本当に完成度が高いのですが、踏み込んだカスタマイズには Vue を書く必要があります。VitePress は設計上、独自のプラグインシステムを持ちません。カスタマイズはカスタムテーマとスロットを通じて Vue に、そして設定とプラグインを通じて Vite に委ねられています。VuePress 2 はより広範な独自のプラグイン/テーマ API を維持しており、設定内でのコンポーネント差し替えもより直接的です。これが、深くカスタマイズされた VuePress サイトを抱えるチームがときに移行せずにとどまる理由です。

この設計には実務上の角があります。デフォルトテーマの Vue コンポーネント内の scoped スタイルを上書きするには、ときに !important が必要になります。サイドバーははるかにシンプルで、サブフォルダーごとに個別のサイドバーを設定できますが、themeConfig.sidebar に手書きで記述する必要があります。新しい Markdown ファイルは、設定を編集するか vitepress-sidebar のようなコミュニティプラグインを追加するまで表示されません。フロントマターは Markdown 内で直接読み取りやすく、prev/next リンクは prev と next を自分で設定しない限りサイドバーから推論されます。自分で設定する場合は、サイドバーに含まれるかどうかを問わず任意のページを指定できます。

VitePress のサイドバー設定はすっきりしています。

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

セクションごとに異なるサイドバーを持たせたい場合は、パスをキーとしたオブジェクト形式（sidebar: { '/guide/': [...] }）を使います。これは VuePress では実現がより難しいマルチサイドバーのパターンです。

VitePress が適さないのはどんなときか

VitePress は意図的にスコープが絞られており、いくつかのギャップは実在します。まず、ファーストパーティのドキュメントバージョニングがありません。v1/v2/v3 を同時に保守するチームは、バージョンごとにフォルダーを分け、サイドバーを手作業で配線することになります。これが Docusaurus を代わりに選ぶ最大の理由です。また、Docusaurus と比べるとプラグインエコシステムは小規模です。ブログ機能も弱く、タグシステム、RSS フィード、アーカイブページのいずれも組み込みでは提供されないため、マーケティング色の強いサイトでは労力に見合いません。そして、Markdown とデフォルトテーマの範囲を超えた瞬間に Vue が必須になります。

ファーストパーティのバージョニングや大規模なプラグインライブラリが明確に必要な場合（それは Docusaurus の領域です）、あるいはスタックが React である場合を除いて、VitePress を選んでください。React スタックなら、Fumadocs、Nextra、Docusaurus のほうが適しています。

VuePress からの移行と最終結論

新しい VitePress サイトのスキャフォールディングはコマンド 4 つで完了します。npm add -D vitepress、続いてセットアップウィザードを実行する npx vitepress init、ローカルサーバーを起動する npm run docs:dev、そして .vitepress/dist に静的出力を書き出す npm run docs:build です。現行の公式ドキュメントではインストールコマンドのデフォルトが 2.0-alpha 系（vitepress@next）になっており、前提条件として Node.js 22 以上が挙げられています。したがって、安定版の 1.x を入れたい場合は素の npm add -D vitepress を使ってください。

VuePress からの移行はそのまま差し替えられるものではありません。Markdown、フロントマター、共通の Markdown 拡張はきれいに引き継げますが、設定スキーマ、テーマ、レイアウトは作り直す必要があり、独自の VuePress プラグインには VitePress の同等物が必要です。デフォルトテーマのサイトが最も容易に移行できます。

判断基準はこうです。新規の Vue ドキュメントサイトなら、迷わず VitePress を選んでください。デフォルトテーマの VuePress サイトを運用しているなら、VitePress へ移行しましょう。ファーストパーティのバージョニングや充実したプラグインライブラリが必要なら、Docusaurus を検討してください。スタックが React なら、最初から React ベースのジェネレーターで始めるべきです。VitePress をインストールして npx vitepress init を実行すれば、設定リファレンスを読み終える前に動くドキュメントサイトが手に入ります。

よくある質問

VuePress は非推奨ですか？

VuePress 1 は非推奨でメンテナンスモードに入っており、VuePress 2 はコミュニティチームに引き継がれ、最終安定版をリリースしないままリリース候補にとどまっています。Vue チームは 2 つのジェネレーターを並行して維持することは持続可能でないと判断し、現在は主要な静的サイトジェネレーターとして VitePress を推奨しています。npm 上でも VuePress コアの 'latest' タグは依然として 1.x 系を指しており、2.0 が RC を抜け出していないことを裏づけています。

VitePress はフォルダー構造からサイドバーを自動生成できますか？

いいえ。VitePress はデフォルトではサイドバーを自動生成しません。新しい Markdown ファイルは、設定ファイル内のサイドバーを手動で編集するか、vitepress-sidebar のようなコミュニティプラグインを導入するまで表示されません。VitePress はパスをキーとした複数サイドバーをサポートしているため、サブフォルダーごとに個別のサイドバーを定義できますが、そのマッピングはディレクトリツリーから導出されるのではなく、明示的に記述する必要があります。

VitePress は Docusaurus のようなドキュメントのバージョニングに対応していますか？

いいえ。VitePress には組み込みのファーストパーティなバージョニング機能はありません。複数のドキュメントバージョンを同時に保守するチームは、バージョンごとにフォルダーを分け、サイドバーを手作業で配線しています。ドロップダウンによる切り替えを伴うバージョン管理された（versioned）ドキュメントが必須要件であれば、ファーストパーティのバージョニングをコア機能の 1 つとする Docusaurus のほうが有力な選択肢です。これは VitePress ではなく React ベースのジェネレーターを選ぶ最も一般的な理由です。

VitePress で踏み込んだカスタマイズをするのに Vue コンポーネントを書く必要があるのはなぜですか？

VitePress は設計上、独自のプラグインシステムを持ちません。独自のプラグイン API を用意する代わりに、カスタマイズはカスタムテーマとスロットを通じて Vue に、そして設定とプラグインエコシステムを通じて Vite に委ねられています。これによりコアは最小限に保たれますが、その分デフォルトテーマの見た目や挙動を上書きするには、設定オプションを切り替えるのではなく Vue コンポーネントを書き、ときには !important で scoped スタイルを強制的に上書きする必要が生じます。