Membuat dan Menjalankan Proyek VitePress dengan ServBay

VitePress adalah generator situs statis modern yang didukung oleh Vue dan dirancang khusus untuk membangun situs dokumentasi yang cepat, menarik, serta mudah dikelola. Berbasis Vite, VitePress menawarkan pengalaman pengembangan serta performa build yang luar biasa. Bagi developer yang membutuhkan dokumentasi profesional untuk proyek, library, atau produk, VitePress menjadi pilihan terbaik.

Saat mengembangkan dan menguji VitePress secara lokal, lingkungan web development yang stabil dan mudah dikonfigurasi sangatlah penting. ServBay hadir sebagai solusi, menyediakan integrasi berbagai versi Node.js dan server web yang kuat (seperti Caddy atau Nginx), sehingga Anda dapat dengan mudah melayani proyek VitePress Anda.

Artikel ini akan memandu Anda memanfaatkan lingkungan terintegrasi ServBay mulai dari membuat, mengonfigurasi, hingga menjalankan proyek VitePress. Termasuk cara mengatur reverse proxy untuk server pengembangan, hingga melayani file statis untuk versi produksi.

Apa itu VitePress?

VitePress adalah Static Site Generator (SSG) yang dibangun di atas Vite, memanfaatkan fitur canggih Vue 3 dan performa cepat Vite untuk menghasilkan situs statis, sangat cocok untuk dokumentasi teknis.

Fitur dan Kelebihan Utama VitePress

• Pengalaman Pengembangan Super Cepat: Berkat Hot Module Replacement (HMR) dari Vite, setiap perubahan bisa langsung dilihat di browser, sangat mempercepat workflow coding.
• Didukung oleh Vue: Anda bisa langsung memakai komponen Vue di file Markdown, membuat dokumentasi lebih interaktif dan ekspresif.
• Sederhana dan Mudah Digunakan: Konfigurasi simple, siap pakai langsung, sehingga Anda fokus pada konten.
• Performa Tinggi: File statis yang dihasilkan sangat ringan dan waktu loading yang cepat. Dengan client-side routing bawaan, pengalaman SPA (Single Page Application) terasa lancar.
• Ramah SEO: Struktur HTML yang dihasilkan mudah terbaca mesin pencari, serta mendukung header tag kustom.
• Markdown yang Ditingkatkan: Mendukung sepenuhnya CommonMark dan GitHub Flavored Markdown (GFM), plus berbagai sintaks tambahan.

Dengan VitePress, developer dapat dengan mudah membangun situs dokumentasi yang berkualitas tinggi dan berkinerja baik.

Membuat dan Menjalankan Proyek VitePress dengan ServBay

ServBay menyediakan cara mudah untuk mengelola versi Node.js sekaligus mengatur server web untuk melayani proyek VitePress Anda, baik pada mode pengembangan maupun mode produksi untuk file statis.

Syarat Awal

Sebelum memulai, pastikan Anda sudah melakukan persiapan berikut:

1. Instal ServBay: Pastikan ServBay sudah terpasang di sistem Anda. Jika belum, lihat panduan instalasi ServBay.
2. Instal Paket Node.js: Di ServBay, pastikan Anda sudah menginstal dan mengaktifkan versi Node.js yang dibutuhkan. Anda dapat mengelolanya lewat halaman "Paket" di panel ServBay. Lihat Penggunaan Node.js.

Membuat Proyek VitePress

1. Inisialisasi Direktori Proyek

   Buka aplikasi terminal Anda. Disarankan untuk membuat folder proyek di root default website ServBay agar mudah dikonfigurasi ke depannya.

   macOS:

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

   Windows:

   cd C:\ServBay\www
   mkdir servbay-vitepress-app
   cd servbay-vitepress-app

2. Instal VitePress dan Inisialisasi Konfigurasi

   Di dalam folder proyek servbay-vitepress-app, gunakan npm atau yarn untuk menginstal VitePress sebagai dependency pengembangan dan jalankan perintah inisialisasi.

   npm add -D vitepress
   npx vitepress init

   Atau dengan Yarn:

   yarn add -D vitepress
   yarn vitepress init

   Perintah inisialisasi akan memandu Anda mengisi pengaturan dasar seperti judul website, deskripsi, dan lain-lain. Ikuti instruksi berikut:

    ┌  Welcome to VitePress!
    │
    ◇  Where should VitePress initialize the config?
    │  ./docs  # Direktori default dokumentasi, tekan Enter untuk konfirmasi
    │
    ◇  Site title:
    │  ServBay VitePress Demo # Masukkan judul website Anda, misal ServBay VitePress Demo
    │
    ◇  Site description:
    │  A VitePress site running on ServBay # Masukkan deskripsi situs
    │
    ◇  Theme:
    │  Default Theme # Pilih tema, gunakan default saja
    │
    ◇  Use TypeScript for config and theme files?
    │  Yes # Pilih apakah ingin menggunakan TypeScript, sesuaikan preferensi Anda
    │
    ◇  Add VitePress npm scripts to package.json?
    │  Yes # Tambahkan skrip ke package.json, disarankan memilih Yes
    │
    └  Done! Now run npm run docs:dev and start writing.

   Setelah selesai, VitePress akan membuat subdirektori docs di dalam servbay-vitepress-app serta file konfigurasi default (.vitepress) dan halaman contoh (index.md, guide/index.md, dsb). File package.json juga akan terupdate dengan skrip seperti docs:dev dan docs:build.

Mengedit Konten Proyek VitePress

1. Edit Konten Beranda

   File halaman depan default VitePress berada di docs/index.md. Anda dapat membukanya dengan editor teks apa saja, lalu mengubah isinya, misal seperti berikut:

   # Hello ServBay!
   
   Selamat datang menggunakan ServBay untuk menjalankan situs dokumentasi VitePress Anda.
   
   Ini adalah demo lokal VitePress yang berjalan via ServBay.

Masuk Mode Pengembangan

Untuk pengembangan situs VitePress, biasanya digunakan server pengembangan bawaan yang mendukung hot reload sehingga Anda dapat langsung mempreview perubahan. Selanjutnya, kita akan gunakan fitur reverse proxy ServBay dengan domain kustom, sekaligus mendapatkan sertifikat SSL otomatis.

1. Menjalankan Server Pengembangan VitePress

   Pastikan terminal Anda berada di root proyek (macOS: /Applications/ServBay/www/servbay-vitepress-app, Windows: C:\ServBay\www\servbay-vitepress-app). Jalankan perintah berikut untuk memulai server pengembangan dan tentukan port (misal 8585).

   npm run docs:dev -- --port 8585

   Atau dengan Yarn:

   yarn docs:dev --port 8585

   Server pengembangan akan aktif dan mendengarkan di port tersebut (misal 8585). Terminal akan menampilkan alamat lokal, biasanya http://localhost:8585.

2. Konfigurasi Situs ServBay (Reverse Proxy)

   Buka panel ServBay kemudian masuk ke halaman "Situs". Klik tambah situs baru.

   • Nama: Masukkan nama mudah diingat, misal Situs VitePress Development.
   • Domain: Masukkan domain pengembangan lokal yang diinginkan. Disarankan pakai akhiran .servbay.demo, misal vitepress-dev.servbay.demo.
   • Tipe Situs: Pilih Reverse Proxy.
   • IP: Isi 127.0.0.1 (localhost).
   • Port: Isi sesuai port server pengembangan, misal 8585.

   Setelah disimpan dan perubahan diterapkan, ServBay akan otomatis mengkonfigurasi server web (Caddy/Nginx) untuk mengarahkan https://vitepress-dev.servbay.demo ke http://127.0.0.1:8585.

3. Mengakses Situs Pengembangan

   Kini Anda bisa membuka browser dan kunjungi domain yang sudah diatur, misal https://vitepress-dev.servbay.demo. Anda akan melihat tampilan dari server pengembangan VitePress. Selain domain kustom, ServBay akan otomatis memberikan sertifikat SSL dari ServBay User CA untuk akses HTTPS yang aman.

Build Versi Produksi

Jika pengembangan dan penulisan dokumentasi telah selesai, saatnya untuk menghasilkan versi statis yang siap dipublikasikan.

1. Build Versi Produksi

   Pastikan terminal Anda berada di root proyek (macOS: /Applications/ServBay/www/servbay-vitepress-app, Windows: C:\ServBay\www\servbay-vitepress-app). Jalankan:

   npm run docs:build

   Atau dengan Yarn:

   yarn docs:build

   Proses build akan mengubah file Markdown, komponen Vue, dsb, menjadi rangkaian file HTML, CSS, JavaScript, yang sudah dioptimalkan. Hasil build berada di docs/.vitepress/dist pada folder proyek.

2. Atur Situs ServBay (File Statis)

   Versi produksi merupakan kumpulan file statis, sehingga dapat langsung dilayani oleh fitur "Static File Service" ServBay.

   Buka panel ServBay lalu masuk ke halaman "Situs" dan tambah konfigurasi baru.

   • Nama: Masukkan nama mudah diingat, misal Situs VitePress Produksi.
   • Domain: Masukkan domain lokal untuk produksi, misal vitepress-prod.servbay.demo.
   • Tipe Situs: Pilih Statis.
   • Root Situs: Isi path absolut ke folder hasil build:
     • macOS: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
     • Windows: C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist

   Simpan dan terapkan perubahan. ServBay akan mengatur server web agar langsung melayani file statis dari root tersebut.

3. Mengakses Situs Produksi

   Sekarang situs dapat diakses lewat browser di domain yang diatur, misal https://vitepress-prod.servbay.demo. Tampilan situs adalah versi final hasil build VitePress. Seperti sebelumnya, ServBay otomatis memberikan domain dan SSL.

Menjalankan Mode Clean URL (cleanUrls: true)

VitePress mendukung pengaturan cleanUrls: true, dimana URL halaman hasil build tidak mengandung ekstensi .html (misal /guide/ tanpa /guide/index.html, atau /about tanpa /about.html). Server web perlu dikonfigurasi agar bisa melayani tipe URL ini.

ServBay menggunakan Caddy atau Nginx sebagai server web. Berikut contoh pengaturan untuk Caddy, dengan instruksi try_files agar sistem mencoba berbagai alternatif file (misal .html atau index.html di dalam folder).

1. Aktifkan cleanUrls pada Konfigurasi VitePress

   Edit file konfigurasi VitePress (docs/.vitepress/config.mts atau docs/.vitepress/config.ts), lalu tambahkan atau rubah opsi cleanUrls:

   // docs/.vitepress/config.mts
   import { defineConfig } from 'vitepress'
   
   export default defineConfig({
     // ... konfigurasi lain
     cleanUrls: true, // Aktifkan clean URL
     // ... konfigurasi lain
   })

   Jalankan kembali npm run docs:build untuk rebuild versi produksi.

2. Konfigurasi Situs ServBay (Custom Caddy Config)

   Buka panel ServBay, masuk ke "Situs", lalu cari situs produksi VitePress Anda (misal vitepress-prod.servbay.demo).

   • Klik tombol edit.
   • Centang opsi Custom Config.
   • Pada area Caddy Config, masukkan isi berikut. Ganti servbay-vitepress-test.prod sesuai domain Anda, dan path root sesuai sistem:
     • macOS: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
     • Windows: C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist

   # Ganti dengan domain Anda, misal vitepress-cleanurl.servbay.demo
   vitepress-cleanurl.servbay.demo {
       # Aktifkan kompresi Brotli (zstd) dan Gzip untuk kecepatan
       encode zstd gzip
   
       # Sertakan konfigurasi log ServBay default untuk debugging
       import set-log vitepress-cleanurl.servbay.demo
   
       # Otomatis tangani sertifikat SSL internal ServBay
       tls internal
   
       # Konfigurasi inti: mencoba urutan file berikut
       # 1. Coba path langsung (misal, /about -> /about)
       # 2. Coba index.html di folder tersebut (misal, /guide/ -> /guide/index.html)
       # 3. Coba menambah .html pada path (misal, /about -> /about.html)
       try_files {path} {path}/index.html {path}.html
   
       # Atur root situs
       # macOS: root * /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
       # Windows: root * C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist
       root * /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
   
       # Aktifkan layanan file statis
       file_server
   }

   Simpan dan terapkan pengaturan.

3. Mengakses Situs Clean URL

   Kini Anda bisa mengunjungi domain yang sudah dikonfigurasi (misal https://vitepress-cleanurl.servbay.demo). Untuk halaman yang clean URL, Anda cukup mengakses tanpa ekstensi .html, misal untuk about.html langsung akses https://vitepress-cleanurl.servbay.demo/about.

Kesimpulan

Dengan tutorial ini, Anda telah mempelajari cara membuat, mengembangkan, dan mendepoy situs dokumentasi VitePress memakai lingkungan ServBay. ServBay memudahkan manajemen versi Node.js serta konfigurasi server web lokal, baik untuk reverse proxy di mode pengembangan maupun layanan file statis pada produksi, semuanya didukung domain kustom serta SSL otomatis.

Manfaatkan kombinasi ServBay dan VitePress untuk membangun serta memelihara dokumentasi teknis berkualitas tinggi secara lebih efektif.