Post-Mortem Evaluasi Pertama: Resolusi Konflik Infrastruktur SSG dan Integrasi CMS

1. Konteks Masalah

Tujuan dari fase pengembangan ini adalah mendeploy aplikasi portofolio berbasis Next.js 16 (App Router) ke infrastruktur cloud (Netlify) dan mengintegrasikan antarmuka Decap CMS. Hal ini dilakukan agar penulisan dokumentasi dapat dieksekusi secara visual tanpa perlu memodifikasi kode sumber (source code) Markdown secara manual.

Eksekusi ini menghadapi serangkaian kegagalan beruntun yang krusial, meliputi: konflik konfigurasi direktori kompilasi (build) di server, hilangnya modul penangkap token otentikasi admin, hingga fatal error pada saat mesin merender tipe data kalender.

2. Kronologi Trial & Error

Proses troubleshooting melewati empat fase kritis sebelum sistem mencapai stabilitas:

• Fase A: Konflik Arsitektur Hosting

  • Tindakan: Memaksa mesin Netlify untuk membaca wujud web statis dari direktori out/ dan mematikan plugin otomatis Next.js bawaan penyedia hosting.
  • Kegagalan: Proses peluncuran (deploy) gagal total dengan status exit code 2. Server Netlify mendeteksi bahwa direktori out tidak eksis.
  • Akar Masalah: Terdapat miskalkulasi arsitektur. Mesin cloud Netlify memiliki sistem bawaan untuk menangani rute Next.js yang secara baku mengompilasi data ke dalam folder .next/. Memaksakan logika statis laptop lokal agar berjalan di server cloud justru mematikan rantai otomatisasi deployment.

• Fase B: Kegagalan Otentikasi Identity

  • Tindakan: Membangun antarmuka Decap CMS menggunakan Git Gateway dan mengirimkan tautan undangan (token) via fitur Netlify Identity ke email.
  • Kegagalan: Saat diklik, tautan undangan gagal memicu jendela (pop-up) pembuatan akun dan kata sandi admin.
  • Akar Masalah: File HTML statis yang bertugas memuat CMS (index.html) belum disisipkan script Netlify Identity Widget. Tanpa script ini, browser tidak memiliki logika untuk mendeteksi, menangkap, dan memproses kode token di dalam URL.

• Fase C: Ledakan Mesin React (Date Object Crash)

  • Tindakan: Memublikasikan dokumen pertama berisi gambar dari dasbor CMS. Netlify menerima instruksi pembaruan dengan benar.
  • Kegagalan: Server gagal merakit ulang halaman beranda (prerendering error) dengan log: Objects are not valid as a React child (found: [object Date]). Seluruh web gagal diperbarui.
  • Akar Masalah: Decap CMS mengirimkan data tanggal publikasi, dan modul pemindai Markdown (gray-matter) secara otomatis menerjemahkannya menjadi format objek kalender (Date object) murni. Mesin visual React menolak mutlak untuk mencetak objek mentah ke layar karena ia hanya menerima tipe data teks biasa (string).

• Fase D: Miskonsepsi Atribut Visual Gambar Markdown

  • Tindakan: Mengisi kolom "Title" saat tahap pengunggahan gambar di CMS dengan harapan ekspektasi akan muncul sebagai teks penjelasan di bawah gambar (caption).
  • Kegagalan: Teks penjelasan tersebut tidak tercetak di antarmuka publik.
  • Akar Masalah: Standar bahasa markup global menerjemahkan kolom atribut title sebagai elemen tooltip (teks yang melayang secara tersembunyi ketika kursor mouse didiamkan pada gambar), bukan sebagai elemen deskripsi teks di bawah gambar.

3. Solusi Final

Infrastruktur portofolio akhirnya beroperasi normal dengan modifikasi permanen berikut:

1. Pendelegasian Infrastruktur: Setelan kompilasi di Netlify dikembalikan sepenuhnya ke standar pabrik (.next). Upaya memaksa Static Site Generation lewat manipulasi rute server dibatalkan, membiarkan cloud menangani manajemen optimasi Next.js secara otonom.
2. Injeksi Modul Identity: Menanamkan <script src="[https://identity.netlify.com/v1/netlify-identity-widget.js](https://identity.netlify.com/v1/netlify-identity-widget.js)"></script> pada struktur kepala (head) file admin/index.html untuk memastikan browser mampu membuka gerbang pendaftaran akun admin.
3. Sanitasi Data Tanggal (Date Interception): Menulis ulang logika penguraian file di dalam src/lib/markdown.js. Tipe data objek kalender dicegat menggunakan kode kondisional if (data.date instanceof Date), lalu secara paksa dimutasi menjadi teks murni data.date.toISOString().substring(0, 10) sebelum disalurkan ke sistem front-end React.
4. Penetapan Standar Penulisan: Pembuatan caption gambar tidak lagi memanfaatkan struktur atribut (metadata) foto, melainkan diketik secara manual menggunakan format cetak miring (italic) pada baris teks tepat di bawah gambar.