Instalasi dan Menjalankan Lokal

Mazer 2.3.1 adalah template Bootstrap 5 yang bisa dipakai tanpa menyentuh source, atau dibangun penuh dari src/ (package.json:1-4¹). README menyediakan beberapa jalur pemakaian: unduh release yang sudah dibangun (README.md:24-27²), build sendiri dengan vite (README.md:29-48), build lewat Docker (README.md:50-56), dan menempel aset dari CDN jsDelivr (README.md:57-58). Halaman ini membahas cara memilih jalur beserta perintah yang dijalankan sampai halaman terbuka di browser. Rincian mesin build ada di Alur Build Vite dan Nunjucks dan Deploy Demo dan Rilis.

Memilih jalur

Pertanyaan penentunya sederhana: apakah kamu perlu mengubah berkas di src/? Kalau tidak, ada dua jalur tanpa Node, yaitu release siap pakai dan CDN. Kalau ya, jalur build sendiri atau Docker yang dipakai.

graph TD
    ask{"Perlu ubah berkas di src/?"}
    ask -->|tidak| release["Unduh release rilis<br/>buka index.html"]
    ask -->|"tidak, tempel ke proyek sendiri"| cdn["CDN jsDelivr<br/>mazer@docs/demo"]
    ask -->|ya| clone["git clone zuramai/mazer"]
    clone --> install["yarn install / npm install"]
    install --> dev["npm run dev"]
    dev --> local["http://localhost:5173"]
    install --> docker["docker build -t mazer-frontend ."]
    docker --> run["docker run -p 5173:80"]
    style ask fill:#f59e0b,color:#000
    style release fill:#2d7d46,color:#fff
    style clone fill:#2d7d46,color:#fff
    style install fill:#2d7d46,color:#fff
    style dev fill:#2d7d46,color:#fff
    style local fill:#2d7d46,color:#fff
    style cdn fill:#8b5cf6,color:#fff
    style docker fill:#f59e0b,color:#000
    style run fill:#f59e0b,color:#000
%% fig: Pohon keputusan jalur pemakaian Mazer
%% desc: Percabangan dari satu pertanyaan menuju release siap pakai, build sendiri dengan vite, build lewat Docker, atau pemakaian lewat CDN jsDelivr.

Jalur release bisa dibuka langsung dari filesystem karena konfigurasi memakai base: './', sehingga URL aset di dist/ ditulis relatif terhadap halaman (vite.config.js:109-112⁶).

Jalur 1: release siap pakai

README menyarankan jalur ini sebagai pilihan utama. Langkahnya hanya mengunduh rilis terbaru dari halaman releases, lalu membuka berkas index.html dan membaca source yang menyertainya (README.md:24-27²). Tidak ada install, tidak ada server, dan tidak ada dist/ yang perlu dibangun ulang.

Jalur 2: build sendiri

Prasyarat dan urutan perintah

Empat langkah yang didokumentasikan README: clone repository, pasang dependensi dengan yarn install atau npm install, jalankan npm run dev, lalu buka http://localhost:5173 (README.md:29-48³). Dependensi yang dipasang mencakup vite 5.0.2 dan vite-plugin-nunjucks ^0.2.0 (package.json:70-84⁷).

git clone https://github.com/zuramai/mazer
cd mazer
yarn install   # atau npm install
npm run dev

Perintah di blok scripts

Blok scripts mendefinisikan delapan perintah yang bisa dijalankan dari akar repository (package.json:5-14⁸). Empat di antaranya relevan untuk kerja lokal.

Sisanya, yaitu prod-rtl, rtl, prettify, dan zip, dipakai untuk keluaran RTL dan paket rilis. Keduanya dibahas di Layout RTL dan Build rtlcss dan Deploy Demo dan Rilis.

Berkas mana yang dilayani saat dev

npm run dev menjalankan vite dengan root yang diarahkan ke src (vite.config.js:109-112⁶). Di root itu, getFiles() mengumpulkan setiap *.html sebagai entry dan nunjucks() memakai direktori yang sama sebagai templatesDir (vite.config.js:13-26⁹, vite.config.js:125-127¹⁰). Karena itu setiap halaman di src/ bisa dibuka di dev server; daftarnya ada di Katalog Halaman dan Ekstensi.

Perbedaan mode terlihat pada layout induk. Ketika isDev bernilai benar, src/layouts/master.html memuat assets/js/app.js sebagai module; di luar itu ia memuat assets/compiled/js/app.js (src/layouts/master.html:35-39¹¹). Nilai isDev sendiri berasal dari mode === 'development' pada vite.config.js (vite.config.js:36¹²). Stylesheet pun dirujuk sebagai assets/scss/app.scss dan assets/scss/themes/dark/app-dark.scss, bukan berkas CSS hasil kompilasi (src/layouts/master.html:35-39¹¹).

Jalur 3: Docker

Dockerfile memakai dua stage. Stage frontend berbasis node:16, menyalin package*.json, menjalankan npm install, menyalin seluruh konteks, lalu menjalankan npm run dev (Dockerfile:1-11). Stage kedua memakai nginx:latest dan menyalin /frontend/dist/ ke /usr/share/nginx/html (Dockerfile:1-11). node_modules/ dan dist/ tidak ikut terkirim ke konteks build karena keduanya tercantum di .dockerignore (.dockerignore:1-2).

Perintah yang didokumentasikan README: docker build -t mazer-frontend ., lalu docker run -it -d -p 5173:80 --name mazer mazer-frontend, lalu buka http://localhost:5173 (README.md:50-56⁴). Pada pemetaan itu, port 5173 host menuju port 80 container, yaitu nginx, bukan dev server vite.

⚠️ Dua README memetakan port yang berbeda. README.md memakai -p 5173:80 dan membuka http://localhost:5173 (README.md:50-56⁴), sedangkan README_INDONESIAN.md memakai -p 8080:80 dan membuka http://localhost:8080 (README_INDONESIAN.md:49-55¹³). Pilih satu dan sesuaikan URL-nya, jangan menyalin keduanya sekaligus.

⚠️ Stage frontend menjalankan npm run dev, yaitu perintah vite (package.json:5-14⁸). Perintah itu menyalakan dev server, bukan build produksi. Isi dist/ saat stage ini berjalan hanya berasal dari pemanggilan build() untuk src/assets/js/app.js yang dieksekusi saat modul vite.config.js dimuat (vite.config.js:88-105¹⁴). Ganti baris tersebut dengan npm run build kalau ingin image memuat HTML hasil Nunjucks dan CSS hasil kompilasi; lihat Alur Build Vite dan Nunjucks.

Jalur 4: CDN jsDelivr

Jalur ini tidak memasang apa pun. Halaman HTML sendiri memuat stylesheet dan script langsung dari jsDelivr, dengan tiga stylesheet di <head> dan beberapa script di akhir <body> (README.md:69-73¹⁵, README.md:77-88¹⁶).

graph LR
    html["index.html"] --> theme["static/js/initTheme.js"]
    theme --> attr["data-bs-theme"]
    html --> cssapp["compiled/css/app.css"]
    html --> cssdark["compiled/css/app-dark.css"]
    html --> iconly["compiled/css/iconly.css"]
    html --> darkjs["static/js/components/dark.js"]
    html --> ps["extensions/perfect-scrollbar"]
    html --> appjs["compiled/js/app.js"]
    appjs --> dash["static/js/pages/dashboard.js"]
    dash --> apex["extensions/apexcharts"]
    style html fill:#f59e0b,color:#000
    style theme fill:#8b5cf6,color:#fff
    style attr fill:#8b5cf6,color:#fff
    style cssapp fill:#8b5cf6,color:#fff
    style cssdark fill:#8b5cf6,color:#fff
    style iconly fill:#8b5cf6,color:#fff
    style darkjs fill:#8b5cf6,color:#fff
    style ps fill:#8b5cf6,color:#fff
    style appjs fill:#8b5cf6,color:#fff
    style dash fill:#8b5cf6,color:#fff
    style apex fill:#8b5cf6,color:#fff
%% fig: Urutan aset pada contoh CDN
%% desc: Satu halaman HTML memuat initTheme.js lebih dulu, lalu tiga stylesheet, lalu script komponen, dengan dashboard.js yang bergantung pada apexcharts.

initTheme.js dimuat paling awal di dalam <body>. Berkas itu membaca localStorage.getItem('theme') dan menyetel data-bs-theme pada elemen html sebelum konten dirender (src/assets/static/js/initTheme.js:1-5¹⁷). Perilaku tema selengkapnya ada di Mode Gelap dan Persistensi Tema.

Jalur assets/compiled/... yang dipakai contoh CDN adalah jalur keluaran build yang sama. Konfigurasi build menaruh entry JS di assets/compiled/js/[name].js dan menaruh aset lain di assets/compiled/<ext>/[name][extname] (vite.config.js:152-174¹⁸).

README juga menyebut prefix yang bisa dipakai berulang, yaitu https://cdn.jsdelivr.net/gh/zuramai/mazer@docs/demo, sehingga satu aset ditulis sebagai prefix ditambah jalurnya (README.md:94-99¹⁹).

Catatan penutup

Tiga hal yang paling sering salah saat menjalankan lokal: membuka http://localhost:5173 padahal perintah yang dijalankan npm run build (tidak ada server), memakai port Docker dari README_INDONESIAN.md sementara perintah diambil dari README.md, dan mengubah berkas di dist/ alih-alih di src/. Untuk yang terakhir, semua perubahan memang harus dilakukan pada source, karena dist/ adalah hasil build.