`shopify theme push` Bilang Sukses Tapi Staging Nggak Berubah? Ada Batas 25 Entri di `order` Array

Saya sedang redesign homepage sebuah toko Shopify klien, ganti susunan section, tambah beberapa blok baru. Alurnya standar: edit templates/index.json, jalankan shopify theme push, lalu buka staging buat cek. CLI-nya balik dengan sukses. Baris demi baris hijau, tanpa satu pun peringatan. Tapi begitu saya refresh staging, halamannya persis seperti sebelumnya. Nggak ada satu pun perubahan saya yang muncul.

Refleks pertama saya salah arah total. Saya pikir ini masalah cache, jadi saya purge semua yang bisa saya purge. Nggak ngaruh. Lalu saya shopify theme pull buat memastikan lokal saya sinkron, dan yang balik justru bikin bingung: konten lama, bukan yang baru saya push. Seolah push saya diterima, di-ACK, lalu diam-diam dibuang. Di titik itu saya mulai curiga theme-nya "terkunci" entah bagaimana, mungkin ada orang lain sedang edit lewat theme editor, mungkin ada lock dari sisi Shopify. Saya habiskan berjam-jam mengejar teori lock itu. Semuanya buang waktu.

Kenapa ini terjadi

Yang akhirnya membongkar teka-teki ini bukan lock apa pun. Ini batas yang tidak terdokumentasi dengan jelas: sebuah JSON template Shopify punya order array yang di-cap keras di 25 entri. Lewat dari 25, push-nya ditolak, tapi output default shopify theme push tetap menampilkan sukses tanpa error apa pun. Staging diam-diam mempertahankan state valid terakhir. Jadi dari luar semuanya kelihatan berjalan mulus, padahal sebenarnya tidak ada byte yang benar-benar berpindah.

Kok bisa saya sampai lewat 25? Ini yang licik. Selama proses redesign, saya tidak selalu menghapus section lama, kadang cuma men-disable-nya biar bisa saya nyalakan lagi nanti. Section yang di-disable itu tetap tersimpan. Lebih parah lagi, ada perilaku auto-restore: kalau definisi sebuah section masih ada di objek sections, Shopify akan mengembalikan id-nya ke order array setiap kali push. Jadi entri yang saya kira sudah saya buang terus muncul lagi. Akumulasi section disabled-tapi-preserved plus auto-restore itu mendorong hitungan ke 26+, dan begitu menyentuh 26, seluruh push jadi no-op yang menyamar sebagai sukses.

Ini pola yang menyesatkan justru karena "sukses" itu bohong. Kalau CLI-nya bilang gagal, saya akan langsung baca error dan selesai dalam lima menit. Yang bikin saya kehilangan sore adalah banner hijau di atas push yang secara diam-diam tidak melakukan apa-apa.

Perbaikannya

Kunci pertama: berhenti percaya output default. Jalankan push dengan flag --json buat memaksa error yang sebenarnya keluar:

shopify theme push --json

Dengan --json, error yang selama ini disembunyikan langsung tampak:

{ "errors": { "templates/index.json": ["order: must have a maximum of 25"] } }

Begitu baca baris itu, semuanya jelas. Bukan lock, bukan cache, bukan theme rusak. Cuma order array yang kelebihan muatan.

Perbaikan sebenarnya adalah menjaga baik order array maupun objek sections tetap di 25 atau kurang. Yang penting: menghapus id dari order saja tidak cukup, karena definisi section yang masih ada di sections akan menyemai ulang id itu di push berikutnya. Jadi saya prune betulan section yang sudah disabled, buang blok definisinya dari objek sections, bukan cuma id-nya dari order:

shopify theme push --json
# baca "order: must have a maximum of 25"
# hapus definisi section basi dari objek "sections", bukan cuma id di "order"

Sebagai guard biar nggak kejadian lagi, saya cek panjang array sebelum menambah instance baru. Kalau ada tooling yang menyusun JSON secara programatik:

if (data.order.length >= 25) {
  throw new Error("order array sudah di batas 25; prune section basi dulu");
}

Dan secara berkala saya audit objek sections buat membuang section yang sudah lama disabled, karena merekalah yang diam-diam menyemai ulang order dan mendorong hitungan lewat batas.

Pelajaran

"Sukses" di CLI bukan bukti bahwa deploy-mu benar-benar mendarat. Kalau shopify theme push bilang sukses tapi staging keras kepala nggak berubah, jangan buru-buru menyimpulkan theme terkunci, jalankan shopify theme push --json dulu dan baca error mentahnya. Batas 25 entri di order itu nyata dan sunyi, dan yang terus menyusup melewatinya adalah section disabled-tapi-preserved yang di-auto-restore dari objek sections. Jaga order dan sections sama-sama di 25 atau kurang, dan prune definisi basi, bukan cuma id-nya. Sejak itu, setiap kali sebuah push terlalu tenang, saya tidak lagi menuduh lock, saya minta CLI-nya berhenti sopan dan tunjukkan error yang sebenarnya.