Peta Mendadak Penuh Watermark: Pindah ke MapLibre dan OpenFreeMap

Pagi itu saya buka proyek dan peta di halaman utama langsung kelihatan aneh. Di atas tile ada lapisan abu-abu besar bertuliskan "API KEY REQUIRED". Bukan satu dua tile, semuanya. Tebakan pertama saya kurang membanggakan: saya salahkan cache browser, lalu ekstensi adblock. Local storage dibersihkan, incognito dicoba, hard refresh berkali-kali. Watermark tetap di situ, tenang, kayak memang tempatnya.

Karena tebakan habis, saya lacak asal tile-nya. Basemap proyek ini pakai raster CARTO, dan ternyata mereka mengubah kebijakan: basemap CARTO sekarang wajib API key [2]. Tanpa key, kita cuma dapat watermark seperti itu. Free tier-nya masih ada, tapi nggak sekamar dengan kata bebas: 5 juta tile request per bulan [2], dihitung gabungan layanan raster dan vektor, dan halamannya terang-terangan menyebut alokasi ini untuk penggunaan non-komersial.

Pasang key atau pindah vendor

Dua pilihan di meja. Pasang key berarti ngelola kuota lima juta tile per bulan plus siap diajak ngobrol kalau lewat batas. Nggak ada yang salah dengan itu, tapi proyek ini jalan di sekeliling peta; saya nggak mau tiap bulan ngecek meteran orang lain. Vendor yang bisa mengubah aturan main semalam, besok bisa saja mengubah syarat lain. Jadi key nggak saya ambil.

Saya pindah ke OpenFreeMap. Public instance-nya gratis tanpa batas jumlah map views dan request [1], tanpa API key, tanpa registrasi, tanpa cookies, dan penggunaan komersial diizinkan [1] secara eksplisit. Model dana-nya donasi. Menurut saya itu malah lebih jujur: kalau suatu hari layanannya berhenti, karena dananya habis, bukan karena saya dianggap pelanggan yang lupa bayar. Atribusi tetap wajib, tapi kalau renderernya MapLibre, terpasang otomatis.

Migrasi tiga komponen tanpa menyentuh tes

Yang ikut pindah ada tiga komponen Leaflet: peta utama di halaman peta dengan clustering dan filter, satu mini-map di halaman detail, satu lagi di modal event. Semuanya tadinya menempel raster tile; sekarang semuanya merender vector tiles pakai MapLibre GL. Panduan migrasi resmi MapLibre [3] meringkas keunggulannya: dukungan rotasi peta, vector tiles, dan globe, plus dataset besar lebih cepat karena rendernya WebGL.

Urus dependency sekalian beres: leaflet dan leaflet.markercluster keluar, maplibre-gl masuk. Biar perpindahan nggak melebar ke seluruh app, saya kunci dua hal: props dan fungsi publik komponen nggak berubah, dan data-testid dipertahankan persis. Empat tes E2E di halaman peta lolos tanpa saya edit satu baris skripnya.

Dark mode juga kebagian perbaikan. Dulu tile digelapkan pakai trik CSS filter invert, dengan hasil yang bisa ditebak. MapLibre punya jalur resmi lewat setStyle, tinggal tunjuk style sesuai tema:

const map = new maplibregl.Map({
  container: el,
  style: isDark
    ? "https://tiles.openfreemap.org/styles/fiord"
    : "https://tiles.openfreemap.org/styles/liberty",
});

// ganti tema tanpa bikin ulang map
map.setStyle(isDark ? FIORD : LIBERTY);

Style light tetap liberty. Untuk dark, awalnya saya tunjuk style yang memang bernama dark. Tebakan lagi, meleset lagi.

Style gelap bawaannya nyaris buta

Style dark itu merender mulus, tanpa error di console. Cuma satu masalah: nyaris nggak kelihatan. Saya potret mode gelapnya dan cek pikselnya: jalan digambar #181818 di atas latar rgb(12,12,12). Kontras keduanya sekitar 1.03:1 menurut hitungan pixel saya sendiri. Buat pembanding, WCAG 2.2 meminta teks punya kontras minimal 4.5:1 [4]. Elemen peta nggak punya angka ambang resmi yang saya temukan, tapi 1.03 nggak perlu diperdebatkan; peta yang harus dibaca mata manusia nggak mungkin lolos dengan jalan nyaris sewarna latar.

Solusinya bukan utak-atik warna layer satu-satu, tapi ganti style. Semua komponen sekarang pakai fiord untuk mode gelap, light tetap liberty. Bukinya sederhana: screenshot dark sebelum dan sesudah saya hitung jumlah warna uniknya, dari 227 melompat ke 5.302 setelah pindah ke fiord. Peta kembali punya hierarki; jalan, label, dan area kebaca lagi.

Dua hal yang natang dari insiden ini. Infrastruktur gratis itu kondisi pinjaman: kebijakannya bisa berubah semalam tanpa drama, dan watermark raksasa di halaman depan ternyata cara paling efektif vendor ngabarinnya. Kedua, dark mode itu keputusan data; gelap itu bukan jaminan terbaca, kontrasnya yang menentukan. Sekarang setiap style baru dicek kontrasnya dulu sebelum dipasang. Dua menit ngecek jauh lebih murah daripada satu malam peta hilang dari wajah produk.

Sumber

1. OpenFreeMap
2. Request an API key for basemaps — CARTO
3. Leaflet migration guide — MapLibre GL JS
4. Understanding SC 1.4.3 Contrast (Minimum) — W3C WAI