Arsitektur Repository

Mazer adalah template dashboard statis. Tidak ada server aplikasi di dalam repository ini. Semua yang dihasilkan adalah berkas HTML, CSS, dan JavaScript di dist yang dibuat oleh Vite dari sumber di src. Karena itu, arsitektur repository lebih tepat dibaca sebagai pembagian tanggung jawab antar jenis berkas, bukan sebagai lapisan backend. CONTRIBUTING.md merumuskan pembagian itu secara ringkas: gaya diubah di berkas scss, layout dan konten diubah di berkas html berbasis Nunjucks atau berkas json pendefinisi konten, dan perilaku aplikasi diubah di berkas js (CONTRIBUTING.md:9-17¹).

Akar Vite ditetapkan ke direktori src lewat resolve(__dirname, 'src') (vite.config.js:13²). Konsekuensinya, setiap path di dalam template dan setiap input build diukur relatif terhadap src, bukan terhadap akar repository.

Peta tanggung jawab modul

Diagram berikut menunjukkan siapa bergantung pada siapa. Panah berarti "dipakai atau dibaca oleh".

graph TD
  PAGES["src/*.html: satu berkas per halaman"]
  LAYOUTS["src/layouts: master, auth, rtl, horizontal, vertical-*"]
  SIDEBAR["src/layouts/sidebar.html"]
  FOOTER["src/partials/footer.html"]
  NAVDATA["src/*.json: sidebar-items dan horizontal-menu-items"]
  VITECFG["vite.config.js"]
  SCSS["src/assets/scss/app.scss"]
  JS["src/assets/js/app.js"]
  MAZERJS["src/assets/js/mazer.js"]
  SIDEBARJS["src/assets/static/js/components/sidebar.js"]
  STATIC["src/assets/static: gambar, font, video, js"]
  DISTCSS["dist/assets/compiled/css"]
  DISTJS["dist/assets/compiled/js"]
  DISTSTATIC["dist/assets"]

  PAGES --> LAYOUTS
  LAYOUTS --> SIDEBAR
  LAYOUTS --> FOOTER
  NAVDATA --> VITECFG
  VITECFG --> PAGES
  PAGES --> SCSS
  PAGES --> JS
  JS --> MAZERJS
  MAZERJS --> SIDEBARJS
  SCSS --> DISTCSS
  JS --> DISTJS
  STATIC --> DISTSTATIC

  style NAVDATA fill:#336791,color:#fff
  style VITECFG fill:#f59e0b,color:#000
  style DISTCSS fill:#8b5cf6,color:#fff
  style DISTJS fill:#8b5cf6,color:#fff
  style DISTSTATIC fill:#8b5cf6,color:#fff
%% fig: Dependensi modul di repository Mazer
%% desc: Halaman Nunjucks bergantung pada layout dan data navigasi, sementara Vite menyatukan SCSS, JavaScript, dan aset statis menjadi keluaran dist.

Tabel berikut memerinci isi tiap modul dan titik masuknya.

Halaman, layout, dan partial

Setiap halaman adalah berkas Nunjucks mandiri di akar src. Berkas src/index.html menetapkan title dan filename, lalu menyatakan extends 'src/layouts/master.html' dan mengisi blok styles serta content (src/index.html:1-14¹¹). Pola yang sama dipakai puluhan halaman lain, dan halaman yang bukan dashboard memilih layout berbeda: layout-rtl.html memakai rtl.html, layout-vertical-navbar.html memakai vertical-navbar.html (src/layouts/master.html:1-14¹²).

master.html adalah kerangka terpadat. Ia menyediakan empat blok: stylesfirst, styles, content, dan js (src/layouts/master.html:8-13⁴). Di dalam body, master.html menyusun div#app yang terdiri atas div#sidebar berisi include "src/layouts/sidebar.html" dan div#main berisi header, blok content, lalu include '../partials/footer.html' (src/layouts/master.html:18-31¹³). Layout auth.html adalah varian paling minimal: hanya div#auth dengan satu blok content, tanpa sidebar dan tanpa skrip aplikasi (src/layouts/auth.html:16-20¹⁴). Rincian mekanisme blok dan pewarisan dibahas di Sistem Layout dan Blok Nunjucks.

Perhatikan campuran bentuk path pada include: sidebar ditulis "src/layouts/sidebar.html" sementara footer ditulis '../partials/footer.html'. Keduanya relatif terhadap templatesDir, yaitu root atau src (vite.config.js:125-127¹⁵).

Konfigurasi Vite sebagai perekat

vite.config.js menyatukan semua modul di atas melalui empat mekanisme.

Pertama, getFiles() membaca isi direktori src, menyaring berkas berakhiran .html, dan memetakan nama tanpa ekstensi ke path absolut (vite.config.js:15-24¹⁶). Peta itu dipakai langsung sebagai rollupOptions.input, sehingga setiap halaman menjadi entry point build tersendiri dan menghasilkan satu berkas HTML di dist (vite.config.js:152-158¹⁷).

Kedua, getVariables(mode) membangun objek variabel per nama berkas. Setiap entri menerima web_title: "Mazer Admin Dashboard", sidebarItems, horizontalMenuItems, dan isDev yang bernilai mode === 'development' (vite.config.js:28-40¹⁸). Objek itu diserahkan ke plugin nunjucks bersama templatesDir: root dan dua filter kustom, containString dan startsWith (vite.config.js:125-141¹⁹). Filter startsWith inilah yang dipakai sidebar untuk menandai item aktif berdasarkan key (src/layouts/sidebar.html:41-49²⁰). Struktur data JSON-nya sendiri dibahas di Data Navigasi Sidebar dan Menu Horizontal.

Ketiga, alias @ menunjuk ke src dan alias ~bootstrap, ~bootstrap-icons, ~perfect-scrollbar, serta ~@fontsource menunjuk ke node_modules (vite.config.js:143-151²¹). Alias inilah yang membuat @import "~bootstrap/scss/bootstrap" dan URL font bootstrap-icons dapat diselesaikan dari app.scss (src/assets/scss/app.scss:5-7²²).

Keempat, viteStaticCopy menyalin tiga kelompok aset: src/assets/static ke assets, font hasil kompilasi ke assets/compiled/css, dan bootstrap-icons.svg ke assets/static/images (vite.config.js:114-119²³). Kelompok keempat berasal dari copyModules, yaitu pemetaan nama modul node_modules ke assets/extensions dengan perilaku berbeda menurut nilai boolean: true menyalin hanya subfolder dist, false menyalin seluruh isi modul (vite.config.js:45-46²⁴, vite.config.js:79-86²⁵).

Titik sambung JavaScript dan SCSS

Gaya masuk lewat satu entry: master.html memuat assets/scss/app.scss dan assets/scss/themes/dark/app-dark.scss sebagai stylesheet (src/layouts/master.html:9-10²⁶). app.scss mengimpor variabel lebih dulu, lalu Bootstrap, bootstrap-icons, font, perfect-scrollbar, dan akhirnya ./mazer (src/assets/scss/app.scss:1-21⁶). Berkas _mazer.scss mengurutkan seluruh override per kategori, dari mixins sampai utilities (src/assets/scss/_mazer.scss:44-98²⁷). Urutan impor dan variabel tema dibahas di Arsitektur SCSS dan Variabel Tema.

Sisi JavaScript punya dua jalur. app.js memanggil featherIcons.replace() dan mengimpor ./mazer (src/assets/js/app.js:1-8⁷), sedangkan mazer.js memasang Bootstrap bundle ke window.bootstrap lalu mengimpor ./../static/js/components/sidebar (src/assets/js/mazer.js:1-7²⁸). Perilaku modul sidebar itu dijelaskan di Komponen Sidebar JavaScript.

Diagram berikut menunjukkan bagaimana satu variabel isDev menentukan sumber skrip yang dimuat halaman.

graph LR
  JSON1["src/sidebar-items.json"] --> VARS["getVariables(mode)"]
  JSON2["src/horizontal-menu-items.json"] --> VARS
  MODE["env.mode dari Vite"] --> VARS
  VARS --> PLUGIN["plugin nunjucks: variables + filters"]
  PLUGIN --> TPL["template src/*.html"]
  TPL --> MASTER["src/layouts/master.html"]
  MASTER -->|isDev true| DEVJS["assets/js/app.js type=module"]
  MASTER -->|isDev false| PRODJS["assets/compiled/js/app.js"]

  style JSON1 fill:#336791,color:#fff
  style JSON2 fill:#336791,color:#fff
  style VARS fill:#f59e0b,color:#000
  style PRODJS fill:#8b5cf6,color:#fff
  style DEVJS fill:#8b5cf6,color:#fff
%% fig: Penyuntikan variabel template dan percabangan sumber skrip
%% desc: getVariables menggabungkan data JSON navigasi dan mode Vite menjadi variabel template, lalu master.html memilih sumber JavaScript sesuai isDev.

Percabangan itu ditulis eksplisit di master.html: saat isDev benar, halaman memuat assets/js/app.js dengan type="module"; saat salah, halaman memuat assets/compiled/js/app.js (src/layouts/master.html:35-39²⁹). Urutan perintah yang menjalankan kedua mode tersebut ada di Instalasi dan Menjalankan Lokal dan Alur Build Vite dan Nunjucks.

Jebakan yang perlu diketahui

⚠️ vite.config.js memanggil build() dari Vite secara langsung di tingkat atas modul, terpisah dari objek yang dikembalikan defineConfig (vite.config.js:88-98³⁰). Panggilan itu menghasilkan dist/assets/compiled/js/app.js dalam format umd dengan nama library app, yaitu berkas yang dirujuk cabang isDev bernilai salah. Jika panggilan tersebut dihapus, template hasil build akan menunjuk skrip yang tidak ada.

⚠️ Semua perubahan harus dibuat di src, bukan di dist. CONTRIBUTING.md meminta agar berkas hasil build tidak di-commit dan menekankan untuk selalu menjalankan build dan menguji hasilnya sebelum membuat commit (CONTRIBUTING.md:9-17¹). dist juga dibersihkan sebagian oleh emptyOutDir: false yang justru mempertahankan isi lama (vite.config.js:91³¹).

Skrip di package.json memperlihatkan konsekuensi lain dari pembagian ini: build menjalankan vite build lalu prettify pada dist/*.html, sedangkan prod-rtl menjalankan build lalu rtl yang memproses ulang CSS di dist/assets/compiled/css (package.json:5-14³²). Keduanya bekerja pada keluaran, bukan pada sumber. Rantai RTL tersebut diuraikan di Layout RTL dan Build rtlcss.

Daftar halaman demo yang menjadi entry build, beserta ekstensi yang dipakai tiap halaman, dijelaskan di Katalog Halaman dan Ekstensi. Vite yang dipakai adalah versi 5.0.2 (package.json:81³³).