Sayudha

07 Tools Lokal VS Code Extension, Prettier, LiquidDoc

Properties2
descriptionNyiapin editor lokal biar Liquid berwarna, auto-complete, rapi otomatis, dan snippet punya dokumentasi
tagsshopify, theme, dasar

11 menit baca

Di 06 Theme Editor dan Code Editor kita lihat editor di dalam Shopify admin. Sekarang balik ke komputer sendiri: tiga alat yang bikin VS Code kita ngerti Liquid.

Tanpa alat ini, ngoding Liquid di VS Code itu kaya nulis di Notepad: semuanya satu warna, gak ada auto-complete, dan salah ketik baru ketauan pas dibuka di browser. Tiga alat ini yang ngubahnya:

  1. Shopify Liquid VS Code extension, extension resmi yang ngasih pewarnaan, auto-complete, deteksi error, dan navigasi.
  2. Shopify Liquid Prettier Plugin, pemformat kode biar semua file gayanya seragam.
  3. LiquidDoc, cara nulis dokumentasi di snippet dan block biar editor bisa ngecek parameter yang kamu kirim.

Shopify Liquid VS Code Extension

Install dari Visual Studio Marketplace. Extension ini juga bisa dipasang di VS Code for the Web, jadi kamu bisa ngoding theme langsung di browser dengan fitur lengkap.

Di baliknya, extension ini jalan di atas Liquid Language Server yang kita bahas di 05 Shopify CLI > Liquid Language Server. Jadi semua fitur di bawah sebenarnya datang dari language server itu, extension-nya cuma jembatan ke VS Code.

1. Syntax Highlighting

Pewarnaan sintaks. Grammar-nya dirawat resmi sama Shopify dan sama persis dengan yang dipakai GitHub buat mewarnai kode Liquid. Jadi tampilan di VS Code dan di GitHub konsisten.

2. Dokumentasi Waktu Hover

Arahkan mouse ke kode Liquid atau HTML manapun, muncul definisi, tipe, dan dokumentasinya. Ini juga jalan buat kode JSON. Di menu hover-nya ada link yang bisa diklik ke referensi resmi di browser.

Ini yang bikin belajar Liquid jauh lebih cepat: gak perlu buka dokumentasi di tab lain, cukup hover.

3. Auto-complete

Extension ini ngelengkapin secara kontekstual:

  1. Tag, filter, object, dan properti object Liquid.
  2. Tag, atribut, dan nilai atribut HTML.
  3. Setting theme, section, dan block. Jadi waktu kamu ketik section.settings., muncul daftar setting yang emang ada di schema section itu.
  4. Kunci terjemahan dari file locale.
  5. Nama snippet waktu ngetik {% render '.
  6. Schema tag, elemen JSON yang valid di dalam {% schema %} dan di config/settings_schema.json.

Jendela info cepat bisa dibuka dengan klik tanda panah di menu completion, atau tekan shortcut completion-nya dua kali. Shortcut-nya Control+Space di macOS maupun Windows.

4. Ganti Nama Elemen HTML

Tekan F2 di sebuah tag HTML, dan tag buka dan tutupnya diganti barengan. Jadi ganti <div> jadi <section> gak perlu nyari </div>-nya.

5. Format Kode

Pemformatan pakai Liquid Prettier Plugin (dibahas di bawah), dan bisa dijalanin:

  1. Otomatis waktu save (butuh setting, lihat bagian Prettier).
  2. Klik kanan > Format Document.
  3. Command Palette > Format Document.
  4. Shortcut Shift+Option+F (Mac) / Shift+Alt+F (Windows).

6. Navigasi Kode

Di theme Shopify ada banyak cara nyertain file lain (render, section, asset_url, dan sebagainya). Extension nandain referensi itu dengan garis bawah, dan kamu bisa loncat ke file-nya pakai Command+Click (Mac) / Control+Click (lainnya).

Kalau file-nya belum ada, VS Code nawarin buat bikinin. Jadi kamu bisa nulis {% render 'product-card' %} dulu, klik, terus langsung bikin snippet-nya.

7. Auto-closing Pairs

Ketik {{ otomatis jadi {{ }}, ketik {% otomatis jadi {% %}, dan seterusnya. Buat HTML juga.

8. Theme Check

Extension ini nyertain Theme Check, linter buat theme Shopify. Kalau ada masalah, muncul garis bergelombang merah (error) atau kuning (warning) di bawah kodenya. Semua diagnostik juga masuk ke tab Problems (Command+Shift+M / Control+Shift+M). Aturan-aturannya dibahas di 65 Theme Check Pengenalan, Konfigurasi, Commands.

9. Fixes dan Suggestions

Ada dua jenis bantuan otomatis, dan bedanya penting:

Fixes (bola lampu biru): masalah yang bisa diperbaiki otomatis tanpa pikir panjang. Bisa diterapin:

  1. Otomatis waktu save.
  2. Klik bola lampu biru > Code Actions.
  3. Klik kanan diagnostik di tab Problems.
  4. Command Palette > Auto fix…, atau shortcut Option+Command+. (Mac) / Control+Alt+. (Windows).

Suggestions (bola lampu kuning): masalah yang punya lebih dari satu solusi atau butuh pertimbangan manusia, jadi gak bisa diterapin otomatis. Kamu harus milih. Bukanya lewat bola lampu kuning, Command Palette > Quick fix…, shortcut Command+. / Control+., atau klik kanan di tab Problems.

Shopify Liquid Prettier Plugin

Prettier itu pemformat kode yang berpendirian (opinionated): dia gak nanya kamu mau gaya apa, dia punya gaya sendiri dan semua kode dipaksa ngikut. Kedengeran kejam, tapi justru itu gunanya: gak ada lagi debat soal spasi, kutip, atau indentasi di tim, semuanya seragam otomatis.

Plugin Liquid ini bikin Prettier ngerti campuran Liquid dan HTML.

1. Install

Install sebagai dev dependency di project theme:

pnpm add -D prettier @shopify/prettier-plugin-liquid

Buat Prettier versi 3 ke atas, plugin-nya wajib dideklarasiin di file konfigurasi .prettierrc:

{
  "plugins": ["@shopify/prettier-plugin-liquid"]
}

❌ salah, di Prettier 3 plugin-nya gak dikenal kalau gak dideklarasiin

{
  "printWidth": 120
}

✅ benar

{
  "plugins": ["@shopify/prettier-plugin-liquid"],
  "printWidth": 120
}

2. Konfigurasi

Opsi yang didukung beserta nilai bawaannya:

  1. printWidth (120), jumlah karakter maksimal per baris sebelum dipotong.
  2. tabWidth (2), jumlah spasi per level indentasi.
  3. useTabs (false), pakai tab atau spasi.
  4. singleQuote (false), pakai kutip tunggal atau ganda di HTML.
  5. liquidSingleQuote (true), pakai kutip tunggal di dalam tag dan object Liquid.
  6. embeddedSingleQuote (true), pakai kutip tunggal di bahasa yang tertanam (JavaScript, CSS, TypeScript di dalam <script>, <style>, atau padanan Liquid-nya).
  7. htmlWhitespaceSensitivity (css), sensitivitas spasi HTML.
  8. singleLineLinkTags (false), cetak tag <link /> dalam satu baris.
  9. indentSchema (false), indentasi isi tag {% schema %}.

Perhatiin bawaannya: HTML pakai kutip ganda, Liquid pakai kutip tunggal. Jadi <div class="card"> tapi {% render 'card' %}. Ini konvensi yang dipakai Dawn dan hampir semua theme resmi.

3. Pakai di Terminal

Sebagai dependency lokal, tambahin script di package.json:

{
  "scripts": {
    "prettier": "prettier"
  }
}

Terus jalanin:

pnpm prettier path/to/file.liquid --write

Flag --write artinya tulis hasilnya ke file. Tanpa itu, Prettier cuma nampilin hasil format di terminal tanpa ngubah file.

Kalau Prettier-nya global:

prettier path/to/file.liquid --write

4. Pakai di VS Code

Ada dua jalan:

Lewat extension Shopify Liquid (paling gampang). Extension itu udah nyertain plugin Prettier-nya, gak perlu install apa-apa. Kalau mau format otomatis waktu save, tambahin di settings.json VS Code:

{
  "[liquid]": {
    "editor.defaultFormatter": "Shopify.theme-check-vscode",
    "editor.formatOnSave": true
  }
}

Lewat extension Prettier biasa. Install extension Prettier, terus install plugin Liquid-nya secara lokal di repository (cara install di atas).

5. Pakai di Editor Lain

Vim: install vim-plug, vim-prettier, dan plugin Liquid-nya lokal di repository.

WebStorm: install plugin Prettier, install plugin Liquid lokal, restart WebStorm, terus di preferences cari Prettier dan tambahin liquid ke Run for files. Centang On save kalau mau format otomatis.

6. Pakai di Browser atau Bundler

Plugin ini nyediain file standalone.js yang bisa dipakai bareng standalone.js milik Prettier. Di browser lewat CDN:

<script src="https://unpkg.com/prettier/standalone.js"></script>
<script src="https://unpkg.com/@shopify/prettier-plugin-liquid/standalone.js"></script>

Terus format kodenya:

prettier.format(YOUR_CODE, {
  plugins: [prettierPluginLiquid],
  parser: 'liquid-html',
});

Dengan bundler (webpack, Rollup, Browserify):

import prettier from 'prettier/standalone';
import liquidPlugin from '@shopify/prettier-plugin-liquid/standalone';
 
prettier.format(YOUR_CODE, {
  plugins: [liquidPlugin],
  parser: 'liquid-html',
});

Ini jarang kepakai buat theme biasa, tapi berguna kalau kamu bikin alat sendiri yang perlu ngerapiin Liquid.

7. Pre-commit Hook

Prettier bisa dipasang sebagai pre-commit hook, jadi file yang di-stage otomatis dirapiin sebelum di-commit. Dengan begitu gak ada kode berantakan yang masuk ke Git, walaupun ada anggota tim yang lupa format. Daftar alat pre-commit yang kompatibel ada di dokumentasi Prettier.

LiquidDoc

Ini alat ketiga, dan ini yang paling mengubah cara kerja kalau kamu serius bikin theme.

Snippet di Liquid itu kaya fungsi: dipanggil pakai {% render %} sambil ngirim parameter. Masalahnya, Liquid gak punya pengecekan apapun soal parameter itu:

  1. Parameter wajib yang lupa dikirim gak nimbulin peringatan.
  2. Parameter yang salah nama lolos diam-diam.
  3. Gak ada pengecekan tipe.
  4. Buat tau parameter apa aja yang diterima snippet, kamu harus baca kodenya.

Contohnya, ini salah ketik dua kali dan gak ada error sama sekali:

{% render 'loading-spinner', produt: product, show_vendorr: true %}

Snippet-nya bakal jalan, cuma product dan show_vendor-nya kosong, dan kamu bakal bingung setengah jam nyari kenapa spinner-nya gak muncul.

LiquidDoc nyelesain ini dengan dokumentasi terstruktur yang bisa dibaca alat. Kamu nulis parameter apa aja yang diterima snippet, terus editor dan Theme Check yang ngecek pemakaiannya secara real-time.

1. Sintaks Dasar

Sintaksnya terinspirasi JSDoc. Ditulis di paling atas file snippet atau block di dalam tag {% doc %}:

{% doc %}
  Provides an example of a snippet description.
 
  @param {string} title - The title to display
  @param {number} [max_items] - Optional maximum number of items to show
 
  @example
  {% render 'example-snippet', title: 'Featured Products', max_items: 3 %}
{% enddoc %}

Ada tiga tag yang didukung: @description, @param, dan @example.

2. Deskripsi

Dua cara nulisnya:

{% doc %}
The description can be placed before any @ annotations without needing a tag.
 
@description You can also use this tag to place a description anywhere.
{% enddoc %}

Catatan:

  1. Tag @description boleh dilewatin, cukup tulis deskripsinya sebelum anotasi @ apapun.
  2. Kalau ada lebih dari satu deskripsi, cuma yang pertama yang muncul waktu hover.
  3. Deskripsi multi-baris otomatis diformat mulai dari baris baru.

3. Parameter

Formatnya: @param {type} name - description

  1. Type (opsional), tipe data dalam kurung kurawal. Harus salah satu dari yang didukung.
  2. Name (wajib), nama parameternya. Buat parameter opsional, bungkus pakai [], contohnya [max_items].
  3. Description (opsional), penjelasan gunanya.

Contoh lengkap:

{% doc %}
  Product card snippet
 
  @param {string} title - Main product title
  @param {number} price - Product price value
  @param {boolean} show_vendor - Whether to display vendor name
  @param {object} product - Product object
  @param {string} [subtitle] - Optional secondary text
{% enddoc %}

Tipe yang didukung cuma empat:

  1. string, teks.
  2. number, angka.
  3. boolean, benar/salah. Ingat, semua nilai di Liquid punya evaluasi truthy atau falsy.
  4. object, tipe Liquid kompleks atau apapun yang bukan primitif (product, collection, dan sebagainya).

4. Contoh Pemakaian

Tag @example nunjukin cara pakai snippet-nya. Boleh lebih dari satu buat nunjukin pola pemakaian yang berbeda:

{% doc %}
  Price display snippet
 
  @param {number} price - Price value
  @param {boolean} [show_compare_at] - Whether to show compare-at price
 
  @example
  {% render 'price', price: product.price, show_compare_at: true %}
 
  @example
  {% render 'price',
    price: variant.price,
    show_compare_at: false
  %}
{% enddoc %}

5. Yang Kamu Dapet di Editor

Setelah snippet punya LiquidDoc:

  1. Hover di nama snippet di tag render nampilin dokumentasi lengkapnya.
  2. Auto-complete nama parameter waktu ngetik di tag render.
  3. Peringatan kalau parameter wajib gak dikirim.
  4. Pengecekan tipe berdasarkan anotasi @param. Kalau tipenya gak cocok, editor nawarin konversi ke nilai fallback: '' buat string, 0 buat number, false buat boolean.

Jadi contoh salah ketik tadi bakal langsung dapet garis bergelombang di produt dan show_vendorr.

❌ tanpa LiquidDoc, salah ketik lolos diam-diam

{% render 'product-card', produt: product %}

✅ dengan LiquidDoc di snippet-nya, editor langsung nandain produt sebagai parameter yang gak dikenal

{% doc %}
  @param {object} product - Product object
{% enddoc %}

6. Integrasi Theme Check

LiquidDoc nyambung ke Theme Check lewat dua kelompok aturan.

Pengecekan dokumentasi (validasi isi {% doc %}):

  1. UniqueDocParamNames, tiap parameter harus namanya unik.
  2. UnsupportedDocTag, tag doc cuma boleh di file snippet.
  3. ValidDocParamTypes, tipenya harus string, number, boolean, object, atau object Liquid yang bukan global.
  4. UnusedDocParam, parameter yang didefinisikan harus beneran dipakai di dalam snippet.

Pengecekan pemakaian (validasi tag render dan content_for):

  1. DuplicateRenderSnippetArguments dan DuplicateContentForArguments, tiap argumen cuma boleh dikirim sekali.
  2. MissingRenderSnippetArguments dan MissingContentForArguments, semua argumen wajib harus dikirim.
  3. UnrecognizedRenderSnippetArguments dan UnrecognizedContentForArguments, argumen yang dikirim harus cocok sama yang didefinisikan.
  4. ValidRenderSnippetArgumentTypes dan ValidContentForArgumentTypes, tipe argumen harus cocok.

Yang content_for itu buat static block, dibahas di 29 Theme Blocks Mendalam. Detail tiap aturan ada di 66 Theme Check Referensi Aturan A–L dan 67 Theme Check Referensi Aturan M–V.

7. Batasannya

Dua hal yang gak bisa dicek:

Nama snippet yang dinamis. Kalau nama snippet-nya dari variabel, pengecekan pemakaian dimatiin karena alatnya gak tau snippet mana yang dimaksud:

{% assign snippetName = 'price' %}
{% render snippetName %}

Yang bisa dicek cuma nama literal:

{% render 'price' %}

Tipe dari object atau variabel. Kalau kamu kirim product.price, alatnya gak ngecek tipenya karena butuh tau isi product dulu:

{% render 'price', price: product.price %}

Yang dicek cuma nilai literal:

{% render 'price', price: 100 %}

Jadi pengecekan tipenya cuma nangkep kesalahan yang jelas (ngirim 'abc' ke parameter number), bukan semua kesalahan.

Ringkasan

  1. Extension Shopify Liquid itu wajib, dia ngasih pewarnaan, hover dokumentasi, auto-complete (termasuk setting dan nama snippet), navigasi ke file, dan Theme Check langsung di VS Code.
  2. Bola lampu biru itu fix otomatis, bola lampu kuning itu saran yang harus kamu pilih sendiri.
  3. Prettier itu pemformat yang berpendirian, gunanya biar gak ada debat gaya kode di tim. Di Prettier 3 plugin-nya wajib dideklarasiin di .prettierrc.
  4. Bawaannya HTML pakai kutip ganda, Liquid pakai kutip tunggal, dan lebar baris 120 karakter.
  5. Extension Shopify Liquid udah nyertain Prettier, tinggal set editor.formatOnSave di settings.json buat [liquid].
  6. Liquid gak ngecek parameter snippet sama sekali, salah ketik nama parameter lolos diam-diam. Itu masalah yang diselesain LiquidDoc.
  7. LiquidDoc ditulis di {% doc %} di paling atas snippet atau block, pakai @description, @param {type} name - desc, dan @example.
  8. Parameter opsional dibungkus [], dan tipenya cuma string, number, boolean, atau object.
  9. Hasilnya: hover dokumentasi, auto-complete parameter, peringatan parameter hilang, dan pengecekan tipe di editor maupun Theme Check.
  10. Batasannya: nama snippet dari variabel gak dicek, dan tipe dari object atau variabel gak dicek, cuma nilai literal.

Bab selanjutnya kita nyambungin theme ke GitHub biar tiap perubahan tercatat, bisa dibalikin, dan otomatis masuk ke toko tiap kali di-push.

Tampilan Grafik

Tautan Balik