Upload Tema Shopify Ditolak `theme_author too long` dan `default can't be blank`? Batas Schema yang Baru Muncul Saat Push

Saya lagi mengapalkan sekitar 13 section baru ke tema Shopify sebuah toko klien, semuanya sudah jalan mulus di lokal, tinggal shopify theme dev untuk push ke store development dan lihat hasilnya. Yang saya harapkan cuma satu putaran verifikasi. Yang saya dapat adalah antrean penolakan schema yang datang satu demi satu, seperti dikuliti pelan-pelan.

Refresh pertama: upload ditolak, theme_author too long. Saya perbaiki, refresh lagi. Sekarang invalid range step di section lain. Perbaiki, refresh. Sekarang default can't be blank. Perbaiki, refresh. default can't be blank lagi, di setting yang berbeda. Lalu error escaping apostrof di sebuah string Liquid. Setiap perbaikan cuma membuka error berikutnya, karena dev server berhenti di kesalahan pertama yang dia temukan dan tidak pernah menunjukkan sisanya sekaligus.

Kenapa error-nya muncul satu per satu

Yang bikin frustrasi bukan error-nya sendiri, tapi ritmenya. settings_schema.json dan schema per-section punya sejumlah batas keras yang tidak dicek di lokal dan baru ketahuan saat upload. Dev server memvalidasi schema saat kamu push, gagal di aturan pertama yang dilanggar, dan berhenti. Jadi kalau ada lima pelanggaran, kamu butuh lima siklus refresh untuk menemukan semuanya. Tidak ada linter di editor saya yang menangkap ini lebih dulu.

Batas-batas yang menyenggol saya, semuanya bukan hal yang kelihatan salah saat menulis schema:

theme_author harus maksimal 25 karakter. Punya saya berbunyi seperti Nama Studio (WeAreBrand) yang panjangnya 28 karakter, jadi ditolak.
Sebuah range control harus memenuhi rumus (max - min) / step + 1 <= 101 langkah diskrit. Saya menulis range untuk radius pill dengan min 0, max 999, step 1, yang berarti 1000 langkah, jauh di atas batas 101.
Setting bertipe text, textarea, dan richtext menolak "default": "". Default schema kosong itu dianggap tidak valid. Bukan diabaikan, tapi ditolak mentah-mentah.
Sebuah string Liquid dengan apostrof yang saya escape pakai '\'' bikin parser tersedak.

Tidak satu pun dari ini yang tampak seperti bug saat kamu mengetiknya. Range 0 sampai 999 itu wajar. Author string dengan nama studio itu wajar. "default": "" kelihatan seperti cara sopan bilang "tidak ada nilai awal". Tapi validator schema Shopify tidak setuju, dan dia cuma bilang begitu satu error dalam satu waktu.

Perbaikannya: sweep schema sebelum push

Pelajaran sebenarnya bukan cara memperbaiki tiap error, tapi berhenti menemukannya secara reaktif. Sekarang saya menjalankan pre-flight sweep di seluruh schema sebelum push, jadi semua pelanggaran ketahuan sekaligus alih-alih satu per refresh.

Untuk theme_author, saya cukup pendekkan agar 25 karakter atau kurang. Untuk setiap range, saya hitung (max - min) / step + 1 dan pastikan hasilnya <= 101. Radius pill tadi saya ubah dari max 999 menjadi max 100:

{
  "type": "range",
  "id": "pill_radius",
  "label": "Pill radius",
  "min": 0,
  "max": 100,
  "step": 1,
  "unit": "px",
  "default": 8
}

Dengan min 0, max 100, step 1 hasilnya (100 - 0) / 1 + 1 = 101 langkah, tepat di batas. Range 0..999 sebelumnya menghasilkan 1000 langkah dan itulah yang memicu invalid range step.

Untuk default kosong, saya grep semua file .liquid dan .json mencari string default yang blank, lalu isi atau hapus:

grep -rn '"default": *""' sections/ snippets/ config/

Aturan yang saya pegang: kalau sebuah setting text, textarea, atau richtext tidak punya nilai awal yang masuk akal, saya hilangkan saja key default-nya sama sekali. Menghapus key default berarti "tidak ada default", dan itu valid. Menuliskannya sebagai "default": "" tidak valid.

Satu jebakan penting yang perlu dipisahkan: nilai kosong di dalam file templates/*.json itu boleh. Field di sana bukan default schema, melainkan nilai yang diisi user lewat theme editor, jadi kosong di situ sah dan bukan yang bikin upload ditolak. Yang divalidasi ketat adalah default di schema, bukan nilai di template.

Untuk escaping apostrof di string Liquid, saya berhenti pakai trik '\''. Kalau string-nya perlu apostrof, saya bungkus dengan tanda kutip ganda:

{{ "don't show this again" }}

Pakai "don't" dengan kutip ganda jauh lebih bersih daripada mengurai apostrof di dalam kutip tunggal.

Checklist pre-flight schema

Sebelum push tema dengan banyak section baru, saya sekarang sweep dulu:

Hitung (max - min) / step + 1 untuk SETIAP range, pastikan <= 101. Kalau lewat, naikkan step atau turunkan max.
Cek theme_author di settings_schema.json maksimal 25 karakter.
Grep "default": *"" di semua .liquid dan .json, lalu hapus key atau isi nilainya. Ingat: default kosong hanya masalah di schema, bukan di templates/*.json.
Apostrof di string Liquid, bungkus dengan kutip ganda, jangan escape di dalam kutip tunggal.

Dev server Shopify tetap akan mengungkap masalah satu per satu kalau kamu membiarkannya. Kuncinya adalah tidak menyerahkan pekerjaan itu ke dev server. Semua batas ini bisa dihitung dari file di lokal sebelum satu byte pun dikirim, dan sweep lima menit menghemat lima belas refresh yang menyakitkan.