ServBayでVitePressプロジェクトを作成・運用する

VitePressは、Vueベースのモダンな静的サイトジェネレーターであり、高速かつ美しい、保守しやすいドキュメントサイトを構築するために設計されています。Viteのテクノロジーを活かし、優れた開発体験とビルドパフォーマンスを実現しています。プロジェクトやライブラリ、製品などの専門的なドキュメントを作成したい開発者にとって、VitePressは最適な選択肢です。

ローカルでVitePressの開発・テストを行う際には、安定して設定しやすいローカルWeb開発環境が不可欠です。ServBayはまさにそのためのツールであり、複数バージョンのNode.js環境やパワフルなWebサーバー（Caddy/Nginxなど）を統合し、VitePressプロジェクトのサービングを簡単に実現します。

本記事では、ServBayの統合環境を活用し、VitePressプロジェクトをゼロから作成・設定・運用する手順を紹介します。開発サーバーのリバースプロキシ設定や、本番用ビルドでの静的ファイル提供も含まれます。

VitePressとは？

VitePressは、Viteをベースとした静的サイトジェネレーター（SSG）であり、Vue 3の柔軟性とViteの高速さを活用した静的サイトの構築が可能です。特にテクニカルドキュメントの作成に強みがあります。

VitePressの主な特徴とメリット

• 超高速な開発体験: Viteのホットモジュールリプレース（HMR）により、更新内容がブラウザに即時反映され、開発効率が飛躍的に向上します。
• Vue駆動: Markdownファイル内でVueコンポーネントを直接利用可能。ドキュメントのインタラクション性や表現力を大幅強化します。
• シンプルな操作性: 手軽な設定ですぐに使え、コンテンツ作成に集中できます。
• 高パフォーマンス: 生成される静的ファイルが軽量かつ高速。SPAライクな滑らかな操作感も提供されます。
• SEO対策も万全: 出力HTMLは検索エンジンに最適化され、カスタムのヘッドタグ挿入もサポート。
• 拡張されたMarkdown: CommonMarkとGitHub Flavored Markdown (GFM)の全機能をサポートし、さらなるシンタックスシュガーも提供。

VitePressを使うことで、開発者は高品質かつ高速なドキュメントサイトの構築が簡単に実現できます。

ServBayでVitePressプロジェクトを構築・運用する

ServBayは、Node.jsバージョン管理やWebサーバー設定を効率化し、開発・本番どちらの環境でもVitePressを手軽に運用できるプラットフォームです。

前提条件

作業開始前に、以下の準備ができていることを確認してください：

1. ServBayのインストール：macOSにServBayがインストールされていること。未インストールの場合はServBayインストールガイドを参照してください。
2. Node.jsパッケージのインストール：ServBay上で必要なバージョンのNode.jsパッケージが導入・有効化されていること。ServBayコントロールパネルの「パッケージ」ページから管理できます。Node.jsの使い方も併せてご覧ください。

VitePressプロジェクトの作成

1. プロジェクトディレクトリの初期化

   まずはターミナルを開きます。ServBayのデフォルトWebルートディレクトリ/Applications/ServBay/www配下にプロジェクトフォルダを作成することを推奨します（サーバー設定が容易なため）。

   cd /Applications/ServBay/www
   mkdir servbay-vitepress-app
   cd servbay-vitepress-app

2. VitePressのインストールと初期設定

   プロジェクトディレクトリservbay-vitepress-appにて、npmまたはyarnでVitePressを開発依存として追加し、初期化コマンドを実行します。

   npm add -D vitepress
   npx vitepress init

   またはYarnの場合：

   yarn add -D vitepress
   yarn vitepress init

   初期化コマンドを実行すると各種基本設定（サイトタイトル、説明など）を対話的に入力します。表示例： :::no-line-numbers ┌ Welcome to VitePress! │ ◇ Where should VitePress initialize the config? │ ./docs # デフォルトのドキュメントディレクトリ。EnterキーでOK │ ◇ Site title: │ ServBay VitePress Demo # サイトタイトル例：ServBay VitePress Demo │ ◇ Site description: │ A VitePress site running on ServBay # サイトの説明を記入 │ ◇ Theme: │ Default Theme # テーマ選択。デフォルトでOK │ ◇ Use TypeScript for config and theme files? │ Yes # 好みに応じてTypeScript設定を選択 │ ◇ Add VitePress npm scripts to package.json? │ Yes # package.jsonへスクリプト追加。基本的にYes推奨 │ └ Done! Now run npm run docs:dev and start writing. :::

   初期化完了後、servbay-vitepress-appフォルダ配下にdocsサブディレクトリが生成され、デフォルト設定ファイル（.vitepress）やサンプルページ（index.md、guide/index.md等）が作られます。同時に、package.jsonへdocs:devやdocs:build等のnpmスクリプトも追加されます。

VitePressプロジェクトの編集

1. トップページ内容の編集

   デフォルトでトップページはdocs/index.mdにあります。任意のテキストエディターでこのファイルを開き、内容をカスタマイズしましょう。例：

   # Hello ServBay!
   
   ServBayを使ってあなたのVitePressドキュメントサイトを運用しましょう。
   
   このサイトはVitePressで作成され、ServBayから配信されています。

開発モードで起動

VitePressでの開発時は、内蔵開発サーバーがホットリロードを提供し、編集結果をすぐ閲覧できます。ServBayのリバースプロキシ機能により、カスタムドメインとSSL経由でこの開発サーバーへアクセス可能です。

1. VitePress開発サーバーの起動

   ターミナルでプロジェクトルート/Applications/ServBay/www/servbay-vitepress-appに移動し、下記のコマンドで開発サーバーを起動。ポート番号（例：8585）は任意に指定できます。

   npm run docs:dev -- --port 8585

   Yarnの場合：

   yarn docs:dev --port 8585

   開発サーバーが指定ポートでローカル上に起動し、ターミナルにhttp://localhost:8585のようなURLが表示されます。

2. ServBayでサイト（リバースプロキシ）設定

   ServBayコントロールパネルの「サイト」ページで新規サイト構成を追加します。

   • 名前: たとえば VitePress開発サイト 等、分かりやすいものを入力。
   • ドメイン名: ローカル開発用の任意ドメイン。Brand規約や重複を避けるため、.servbay.demoサフィックスを推奨します（例：vitepress-dev.servbay.demo）。
   • サイトタイプ: 「リバースプロキシ」を選択。
   • IP: 127.0.0.1（ローカルホスト）と入力。
   • ポート: 先ほど開発サーバーで指定したポート（例：8585）を入力。

   設定を保存・適用すると、ServBayはWebサーバー（Caddy/Nginx）を自動設定し、https://vitepress-dev.servbay.demo へのリクエストを http://127.0.0.1:8585 へ転送します。

3. 開発サイトへアクセス

   ブラウザで構成したドメイン https://vitepress-dev.servbay.demo へアクセスすると、VitePress開発サーバーの内容が表示されます。ServBayの設定により、独自ドメイン＆ServBay User CA発行によるSSLも標準装備でHTTPSアクセス可能です。

本番ビルド

VitePressドキュメントサイトが完成し、公開準備ができたら、最適化された静的ファイルとして本番ビルドを行いましょう。

1. 本番用のビルド

   ターミナルでプロジェクトディレクトリ/Applications/ServBay/www/servbay-vitepress-appへ移動し、ビルドコマンドを実行します。

   npm run docs:build

   または

   yarn docs:build

   MarkdownやVueコンポーネントなどが最適化された静的HTML・CSS・JavaScript一式に変換され、デフォルトではdocs/.vitepress/distにまとめて保存されます。

2. ServBayでサイト追加（静的ファイルサービング）

   本番サイトは静的ファイル群なので、ServBayの静的ファイルサービング機能で直接公開できます。

   ServBayコントロールパネル「サイト」＞新規追加へ進みます。

   • 名前: 分かりやすく例：VitePress本番サイト
   • ドメイン名: 本番アクセス用のローカルドメイン例：vitepress-prod.servbay.demo
   • サイトタイプ: 「静的」を選択
   • ルートディレクトリ: 上記ビルド成果物のフルパス/Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/distを入力

   設定を保存・適用すると、指定したルート配下の静的ファイルがWebサーバーからダイレクトに提供されます。

3. 本番サイトの確認

   ブラウザから構成したドメイン https://vitepress-prod.servbay.demo へアクセスし、本番用VitePressサイトを確認できます。もちろん独自ドメイン＆自動SSLも付与されます。

クリーンURLモードでの運用 (cleanUrls: true)

VitePressはcleanUrls: true 設定に対応しており、.html拡張子を省いたURL（例：/guide/ や/about）が利用可能です。この動作にWebサーバーが対応するには追加設定が必要です。

ServBayはCaddyまたはNginxをWebサーバーとして採用しており、下記はCaddy用の設定例です。try_files命令を活用し、リクエストに応じて適切なファイル（.htmlやindex.html）へリライトします。

1. VitePress設定でcleanUrlsを有効化

   VitePressの設定ファイルdocs/.vitepress/config.mts または docs/.vitepress/config.tsを開き、siteConfig部にcleanUrlsオプションを追加/修正します。

   // docs/.vitepress/config.mts
   import { defineConfig } from 'vitepress'
   
   export default defineConfig({
     // ... (他の設定)
     cleanUrls: true, // クリーンURLを有効化
     // ... (他の設定)
   })

   npm run docs:buildで本番ビルドを再実行してください。

2. ServBayでカスタムCaddy設定を適用

   ServBayコントロールパネル「サイト」から、本番用VitePressサイト（例：vitepress-prod.servbay.demo）を選択。

   • 編集ボタンをクリック
   • カスタム設定のチェックをON
   • Caddy設定欄へ下記の内容を貼り付け。servbay-vitepress-test.prodや/Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/distなど実環境に合わせ適宜変更してください。

   # 例：vitepress-cleanurl.servbay.demo など実際のドメインに書き換え
   vitepress-cleanurl.servbay.demo {
       # Brotli(zstd)・Gzipによる圧縮を有効化
       encode zstd gzip
   
       # ServBay標準のログ設定（デバッグに便利）
       import set-log vitepress-cleanurl.servbay.demo
   
       # ServBay内部CAによるSSL証明書を自動処理
       tls internal
   
       # try_files：ファイル探索の優先順
       # 1. そのままのパス例(/about)
       # 2. index.html付与例(/guide/→/guide/index.html)
       # 3. .html付与例(/about→/about.html)
       try_files {path} {path}/index.html {path}.html
   
       # サイトのルートディレクトリ指定
       root * /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
   
       # 静的ファイルサービング
       file_server
   }

   設定を保存・適用してください。

3. クリーンURL運用サイトへアクセス

   ブラウザから構成済みドメイン（例：https://vitepress-cleanurl.servbay.demo）へアクセスし、about.htmlなどの拡張子省略URL（例：https://vitepress-cleanurl.servbay.demo/about）でも正しくアクセスできることを確認します。

まとめ

本記事の手順により、ServBay環境下でVitePressによるドキュメントサイトをゼロから構築・開発・本番デプロイまで一通り運用できるようになりました。ServBayはNode.js環境管理やローカルWebサーバーのセットアップを飛躍的に簡易化し、開発時のリバースプロキシ、本番用の静的ファイルサービング、さらには独自ドメイン＆SSL証明書も自動で提供されるため、ストレスなく導入できます。

ServBayとVitePressという強力な組み合わせで、高品質な技術ドキュメントの企画・管理・運用を、より効率的に行いましょう。