Checklist Deployment Next.js di Balik Reverse Proxy

Panduan lapangan untuk memastikan aplikasi Next.js tidak hanya selesai build, tetapi juga benar ketika menerima hostname, header, asset, dan cache dari proxy.

Kenali bentuk deployment yang sebenarnya

Next.js dapat berjalan sebagai static export, server Node.js, atau kombinasi route statis dan dinamis. Reverse proxy harus memahami bentuk yang dipakai. Static export membutuhkan file server, sedangkan App Router dengan route dinamis memerlukan runtime. Sebelum menyentuh konfigurasi proxy, tulis daftar route yang harus dihasilkan saat build dan route yang memerlukan server. Kesalahan klasifikasi membuat halaman terlihat normal di lokal tetapi gagal di production.

Cek output build sebagai artefak, bukan hanya pesan sukses. Pastikan route penting ada, asset manifest terbaca, dan server start memakai port yang disediakan platform. Jika deployment menggunakan container, jalankan image dengan user non-root dan health check. Satu perintah start yang konsisten lebih berharga daripada skrip manual yang hanya diketahui satu orang.

Hostname menentukan jalur request

Aplikasi dengan host-based routing dapat menganggap request yang datang ke hostname tertentu sebagai tenant atau domain utama. Saat menguji lokal, gunakan Host header yang sama dengan konfigurasi root domain atau set environment yang benar. Mengakses IP mentah lalu menyimpulkan route hilang adalah diagnosis palsu. Simpan contoh curl untuk hostname canonical dan hostname alternatif yang memang didukung.

Redirect canonical perlu diuji dari HTTP ke HTTPS, apex ke www, serta URL dengan slash yang tidak konsisten. Pastikan redirect tidak berputar ketika proxy sudah melakukan TLS termination. Header X-Forwarded-Proto, X-Forwarded-Host, dan X-Forwarded-For harus diteruskan sesuai kebijakan platform. Jangan mempercayai semua header dari internet tanpa proxy yang diketahui.

Header cache harus sengaja

Cache-Control yang terlalu agresif dapat menampilkan artikel lama sesudah deployment, sedangkan cache yang terlalu ketat membuat setiap request memukul server. Bedakan HTML, asset fingerprinted, sitemap, dan endpoint dinamis. Untuk halaman yang berubah berdasarkan tanggal publikasi, cache harus memiliki jalur revalidation yang sesuai. Uji response pertama, response sesudah purge, dan response dari edge yang berbeda bila tersedia.

Metadata SEO juga bagian dari cache contract. Title, canonical, alternate language, dan JSON-LD harus berasal dari data yang sama dengan body. Jika proxy menghapus content-type atau mengompresi response secara salah, parser mesin pencari dapat menerima hasil yang berbeda dari browser. Simpan header live untuk route artikel dan route homepage sebagai evidence internal, bukan file yang diunggah ke placement.

Asset dan image optimization

Next.js image optimization sering membutuhkan route khusus dan header yang benar. Pastikan proxy tidak memblokir query parameter image, tidak mengubah content-type, dan tidak menghapus cache key yang relevan. Jika gambar disajikan langsung dari object storage, pastikan URL canonical dan kebijakan hotlinking sesuai. Broken image di bawah fold tetap merupakan bug meskipun hero terlihat baik.

Lakukan smoke test pada CSS, JavaScript, font, favicon, serta minimal satu gambar dari setiap jenis asset. Browser console dan network panel memberi sinyal yang tidak terlihat dari curl HTML. Uji mobile karena beberapa proxy atau image transformer memiliki batas ukuran berbeda. Simpan screenshot setelah lazy-loaded image muncul, tetapi tetap simpan bukti asli di workspace atau Trello saja.

Server actions dan endpoint dinamis

Route action dan endpoint API perlu dibedakan dari page route. Terapkan metode HTTP, ukuran body, dan timeout yang tepat. Proxy yang memaksa semua request menjadi GET dapat membuat form terlihat rusak. Tambahkan proteksi CSRF atau origin check sesuai mekanisme aplikasi. Response error sebaiknya tidak membeberkan stack trace atau environment variable.

Untuk endpoint yang memanggil service pihak ketiga, tentukan retry dan circuit breaker di sisi aplikasi. Jangan membuat proxy mengulang POST tanpa idempotency key. Logging request body penuh juga berbahaya jika berisi data akun. Gunakan request id dan ringkasan status. Uji timeout secara terkontrol dengan mock dependency sebelum incident terjadi.

Revalidation dan tanggal konten

Artikel terjadwal memerlukan aturan yang jelas: apakah route future-dated mengembalikan 404, noindex, atau halaman pratinjau yang dilindungi? Pilih satu perilaku dan dokumentasikan. Setelah tanggal publikasi lewat, revalidation harus membuat artikel tersedia tanpa membuat sitemap dan canonical tertinggal. Uji zona waktu, terutama ketika jadwal disimpan WIB tetapi runtime memakai UTC.

Jangan mengubah tanggal artikel hanya untuk membuat kartu terlihat selesai. Cocokkan kalender editorial, source data, sitemap, dan URL live. Jika ada perbedaan antara target publish pada task dan tanggal source, catat konflik dan minta keputusan. Kejujuran pada tanggal lebih aman untuk SEO daripada memaksa halaman tayang sebelum copy dan monitoring siap.

Observability di edge dan origin

Status HTTP 200 dari edge belum membuktikan origin sehat. Pantau response time, cache status, dan error rate. Bedakan 404 route yang memang belum dipublikasikan dari 404 asset akibat deploy tidak lengkap. Correlate request id edge dengan log origin bila platform menyediakan keduanya. Alert yang baik menyebut route dan wilayah terdampak, bukan hanya angka error global.

Buat checklist rollback yang dapat dilakukan tanpa menghapus bukti. Simpan commit, deployment id, dan waktu perubahan di catatan internal. Jika memakai cache purge, catat scope purge karena purge global dapat menimbulkan spike traffic. Setelah rollback, fetch canonical route dan satu route dinamis, lalu pastikan asset dan metadata kembali konsisten.

Checklist sebelum menyebut production ready

Build hijau adalah syarat awal, bukan akhir. Jalankan smoke test canonical redirect, homepage, satu artikel, satu route dinamis, sitemap, robots, dan endpoint yang penting bagi konversi. Periksa desktop dan mobile. Pastikan tidak ada horizontal overflow, judul terpotong, atau cookie banner menutupi CTA. Untuk referensi pilihan layanan yang mendukung deployment Node.js, halaman layanan Node.js hosting dapat menjadi titik awal riset vendor.

Terakhir, minta orang lain membaca checklist tanpa konteks. Jika ia tidak tahu URL mana yang diuji, bukti apa yang disimpan, atau kapan harus rollback, proses masih terlalu bergantung pada ingatan operator. Deployment yang matang bukan yang tidak pernah gagal, melainkan yang kegagalannya cepat diketahui dan mudah dipulihkan.

Catatan lapangan

Catatan lapangan: pengujian proxy paling efektif dilakukan sebagai matriks kecil. Barisnya adalah homepage, artikel, sitemap, asset gambar, endpoint dinamis, dan redirect canonical. Kolomnya adalah request langsung ke origin, request lewat proxy, cache pertama, cache kedua, dan request tanpa cookie. Isi setiap sel dengan status, content type, cache status, serta apakah canonical dan JSON-LD tetap sama. Matriks ini cepat menemukan bug seperti HTML yang benar tetapi sitemap masih memakai hostname origin, atau gambar yang 200 tetapi mempunyai content type text/html. Jalankan matriks sesudah konfigurasi berubah dan simpan hasilnya sebagai artefak internal. Jangan menaruh export jaringan, token, atau header autentikasi di halaman publik. Evidence yang aman cukup berupa ringkasan angka dan tautan Trello privat, sedangkan detail sensitif tetap berada pada workspace yang aksesnya terbatas.

Catatan implementasi

Checklist yang baik menghasilkan bukti yang bisa dibaca orang lain. Simpan waktu probe, hostname, status akhir, dan commit yang sedang dipakai. Jika satu hasil berubah setelah cache purge, jelaskan perubahan itu dan jangan menggabungkan dua waktu pengukuran. Saat membandingkan layanan layanan Node.js hosting dengan opsi lain, masukkan kemampuan proxy, logging, rollback, dan date-gated publishing ke matriks, bukan hanya spesifikasi resource. Dengan cara itu keputusan deployment Next.js dapat dipertanggungjawabkan ketika route dinamis, asset, atau sitemap berubah pada rilis berikutnya.

Studi kasus

Studi kasus singkat: sebuah situs dokumentasi dipindahkan dari server file ke aplikasi Next.js dengan App Router. Homepage tampil normal, tetapi crawler menerima canonical origin dan beberapa file JavaScript berstatus 200 dengan content type yang salah. Masalah pertama berasal dari proxy yang membentuk hostname dari header yang tidak dipercaya. Masalah kedua berasal dari fallback file server yang mengembalikan HTML untuk path asset yang tidak ditemukan. Tim membuat matriks enam route dan empat kondisi cache, lalu menyimpan header response di workspace privat. Mereka menetapkan satu sumber untuk canonical, sitemap, alternate language, dan JSON-LD. Setelah header X-Forwarded-Proto dibatasi pada proxy resmi, redirect tidak lagi berputar. Setelah fallback asset diubah menjadi 404, browser console menjadi bersih. Mereka juga menambahkan smoke test yang mengunduh satu CSS, satu font, satu gambar, satu artikel, dan sitemap pada setiap deployment candidate. Cache purge tidak lagi dianggap sebagai solusi; hasil purge dibandingkan dengan response dari edge setelah masa propagasi. Ketika artikel future-dated diuji, route memang 404 dan tidak masuk sitemap sebelum threshold publikasi. Setelah tanggalnya lewat, test yang sama menjadi 200 tanpa perubahan manual. Case ini menunjukkan bahwa proxy adalah bagian dari aplikasi, bukan pipa transparan yang boleh diasumsikan benar.

Lembar kerja khusus

Worksheet proxy: request `/` dengan Host canonical, lalu ulangi dengan Host origin untuk memastikan redirect yang diharapkan. Periksa apakah `x-forwarded-proto` konsisten setelah TLS termination. Bandingkan `content-type` untuk HTML, CSS, JavaScript, font, SVG, dan WebP. Simpan nilai `cache-control`, `etag`, `age`, dan `vary` dari edge. Pastikan asset fingerprint tidak menerima cookie yang mengubah cache key. Coba URL dengan encoded slash dan query tracking yang aman. Pastikan sitemap memakai hostname publik, bukan container hostname. Bandingkan canonical halaman dengan URL final sesudah redirect. Uji `robots.txt` dan `sitemap.xml` tanpa header browser. Buka artikel dengan cookie kosong dan cookie consent untuk melihat variasi HTML. Jalankan satu route yang memakai server action dan periksa method request. Kirim payload besar sintetis di bawah batas lalu satu di atas batas. Putus koneksi client dan amati apakah origin menghentikan pekerjaan. Uji response 404 asset agar tidak berubah menjadi halaman 200. Periksa `content-encoding` dan ukuran response sesudah kompresi. Dismiss banner consent sebelum screenshot mobile. Scroll sampai gambar lazy-loaded terdecode. Simpan screenshot desktop dan mobile di workspace privat. Cocokkan build commit dengan deployment id. Setelah purge, tunggu propagation dan ulangi route matrix. Verifikasi halaman future-dated tetap konsisten dengan sitemap. Tetapkan satu pemilik untuk rule proxy agar konfigurasi tidak drift. Anggap cache sebagai state yang harus diuji, bukan tombol ajaib.