Mengonfigurasi vercel.json untuk Website Statis: Rewrites, Header Cache, dan Build

Pengertian

Vercel adalah platform hosting yang membangun dan menyajikan situs langsung dari repositori Git. Untuk proyek statis murni, Vercel bisa bekerja tanpa konfigurasi, tetapi begitu Anda butuh URL bersih, aturan cache, atau URL alternatif, dibutuhkan berkas vercel.json.

Berkas ini mengontrol:

• perintah build dan folder keluaran,
• aturan rewrite (memetakan URL ke berkas tanpa mengubah alamat di browser),
• redirect (mengubah alamat secara permanen/sementara),
• header respons, termasuk Cache-Control dan header keamanan,
• perilaku trailingSlash (garis miring di akhir URL).

Kelebihan

• Nol server: cukup push ke Git, Vercel membangun dan menyebarkan otomatis.
• Preview deployment: setiap pull request mendapat URL pratinjau.
• HTTPS dan CDN otomatis: sertifikat dan distribusi global tanpa konfigurasi.
• Aturan kaya: rewrite, redirect, header, dan geolokasi dalam satu berkas.
• Rollback instan: kembali ke deployment sebelumnya lewat dashboard.
• Gratis untuk proyek pribadi dengan kuota yang longgar.

Kekurangan

• Kurang cocok untuk backend berat: fungsi serverless punya batas waktu dan memori.
• Vendor-specific: konfigurasi vercel.json tidak berlaku di platform lain.
• Cache agresif bisa merepotkan: aset lama bisa tersimpan terlalu lama bila salah konfigurasi.
• Log dan debugging terbatas dibanding VPS yang Anda kelola sendiri.
• Rewrites tidak selalu ideal untuk SEO: gunakan redirect bila ingin URL lama digantikan.

Struktur vercel.json

Contoh lengkap untuk situs statis dengan folder keluaran public/:

{
  "version": 2,
  "framework": null,
  "buildCommand": "npm run vercel:build",
  "outputDirectory": "public",
  "trailingSlash": true,
  "rewrites": [
    {
      "source": "/kategori/:slug/",
      "destination": "/kategori.html?kategori=:slug"
    }
  ],
  "headers": [
    {
      "source": "/(.*)\\.(css|js|mjs|json|xml|webmanifest|png|jpe?g|gif|svg|webp|avif|ico|woff2?|ttf|map)
quot;,
      "headers": [
        {
          "key": "Cache-Control",
          "value": "public, max-age=604800, stale-while-revalidate=31536000"
        }
      ]
    }
  ]
}

Penjelasan tiap kunci:

URL Bersih dengan Rewrites

Artikel di proyek ini dirender menjadi /<slug>/index.html. Vercel menyajikan index.html di dalam folder secara otomatis, sehingga /deploy-bot/ bekerja tanpa aturan tambahan.

Rewrites berguna saat sebuah halaman bukan file fisik, misalnya arsip kategori yang diparameterkan:

{
  "rewrites": [
    { "source": "/kategori/:slug/", "destination": "/kategori.html?kategori=:slug" }
  ]
}

Halaman kategori.html membaca :slug lewat query string dan merender daftar artikel dari JavaScript.

Header Cache untuk Aset Statis

Aset berversi (CSS, JS, gambar, font) boleh disimpan lama di browser. Pola aman:

public, max-age=604800, stale-while-revalidate=31536000

• max-age=604800 — browser memakai cache selama 7 hari.
• stale-while-revalidate=31536000 — selama 1 tahun browser boleh menyajikan versi lama sambil memperbarui di latar belakang.

Untuk HTML, biarkan tanpa cache panjang (Vercel mengaturnya pintar secara bawaan) agar perubahan konten langsung terlihat.

Menambahkan Header Keamanan

{
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        { "key": "X-Content-Type-Options", "value": "nosniff" },
        { "key": "X-Frame-Options", "value": "SAMEORIGIN" },
        { "key": "Referrer-Policy", "value": "strict-origin-when-cross-origin" },
        { "key": "Strict-Transport-Security", "value": "max-age=63072000; includeSubDomains; preload" }
      ]
    }
  ]
}

Header CSP sebaiknya ditambahkan bertahap dengan Content-Security-Policy-Report-Only agar tidak mematahkan skrip yang ada.

Perintah Deploy dari Terminal

npm install -g vercel
vercel            # deploy preview
vercel --prod     # deploy produksi
vercel env add TURSO_AUTH_TOKEN production

Untuk membangun secara lokal tanpa mengunggah:

vercel build

Alur yang Dipakai Situs Ini

node scripts/build-articles.js && node scripts/prep-output.js && pagefind --site public

Kombinasi ini: pre-render artikel ke /<slug>/, menyalin seluruh aset ke public/, lalu membangun indeks pencarian Pagefind — semuanya sebelum Vercel menyajikan public/.

Troubleshooting

• Halaman 404 padahal build sukses: pastikan outputDirectory cocok dengan folder keluaran dan HTML benar-benar berada di dalamnya.
• Rewrites tidak jalan: periksa trailingSlash. Rewrite ke /kategori/:slug/ perlu trailingSlash: true; jika false, gunakan /kategori/:slug.
• Loop redirect: jangan buat redirect dari suatu URL ke URL yang juga diarahkan kembali.
• Aset lama terus tampil: naikkan versi di query string (styles.css?v=2) atau kurangi max-age.
• Build gagal di Vercel tapi lancar di lokal: kunci versi Node lewat engines di package.json, dan jalankan npm ci untuk memastikan package-lock.json sinkron.
• Pagefind 404 di produksi: pastikan pagefind dijalankan setelah prep-output.js dan folder hasilnya masuk ke public/pagefind/.

Kesimpulan

vercel.json adalah pengendali utama perilaku situs di Vercel: menentukan perintah build, folder keluaran, URL bersih, dan aturan cache. Untuk situs statis, konfigurasi minim seperti contoh di atas sudah cukup — sisanya ditangani otomatis oleh Vercel.