Sayudha

65 Theme Check Pengenalan, Konfigurasi, Commands

Properties2
descriptionTheme Check sebagai linter Liquid dan JSON theme, cara jalanin lewat CLI, VS Code, dan code editor admin, command shopify theme check dan semua flag-nya, file .theme-check.yml (root, extends, require, ignore, setting per check), severity error/warning/info dan --fail-level di CI, nonaktifin check lewat komentar Liquid, auto-correct, check performa yang opt-in, alur kerja, dan migrasi dari Theme Check 1.x ke 2.x
tagsshopify, theme, tools

10 menit baca

Theme Check udah disebut di lebih dari sepuluh bab sebelumnya, tiap kali ada aturan yang nangkep kesalahan tertentu. Sekarang kita bahas alatnya sendiri: cara install, jalanin, konfigurasi, dan nyambungin ke alur kerja. Dua bab berikutnya bakal bedah semua 80 aturannya.

Theme Check itu linter buat Liquid dan JSON di theme dan theme app extension. Dia ngedeteksi error dan memaksakan praktik terbaik Liquid: syntax error, template yang hilang, variabel dan snippet yang gak dipakai, tag yang gak dikenal atau deprecated, dan masalah performa. Error tampil langsung di console atau editor, dan tiap error nyertain link ke dokumentasi check yang gagal.

Bedanya sama alat performa dari 57 Performance Dasar, Metrik, dan Cara Ngukur: Theme Check itu analisis statis, ngebaca kode tanpa ngejalaninnya, jadi bisa nangkep masalah sebelum runtime, di tiap commit. Dia gak bisa ngukur seberapa lambat, tapi bisa nunjukin pola yang pasti bikin lambat atau rusak.

Tiga Cara Pakai

  1. Shopify CLI: shopify theme check, on demand, di CI, atau lewat Language Server. Butuh @shopify/cli dari 05 Shopify CLI.
  2. VS Code extension Shopify Liquid dari 07 Tools Lokal VS Code Extension, Prettier, LiquidDoc: Theme Check udah termasuk, error muncul inline waktu ngetik.
  3. Code editor admin dari 06 Theme Editor dan Code Editor: sejak Januari 2024, Theme Check 2.x terintegrasi di sana juga.

Buat editor lain, Theme Check tersedia lewat Language Server Shopify. Dan Theme Check open source di repo theme-tools, kamu bisa nulis check sendiri di TypeScript dan ngerujuknya di konfigurasi.

Command

shopify theme check [flags]

Flag-nya (tiap flag juga punya environment variable SHOPIFY_FLAG_*):

  1. --config <path> / -C: path ke config kustom, nimpa .theme-check.yml di direktori yang dianalisis.
  2. --fail-level <level>: severity yang bikin run gagal (exit code 1): error, suggestion, atau style. Buat CI.
  3. --auto-correct / -a: perbaiki otomatis pelanggaran yang bisa diperbaiki.
  4. --init: bikin file .theme-check.yml baru.
  5. --output <format> / -o: format hasil, json atau text (default). JSON buat diproses alat lain.
  6. --print: cetak config yang aktif ke STDOUT, berguna buat debug konfigurasi bertingkat.
  7. --list / -l: daftar check yang aktif.
  8. --environment <env> / -e: environment dari shopify.theme.toml (05 Shopify CLI).
  9. --version / -v: versi Theme Check.
  10. --path <path>: path direktori theme (atau subfolder, shopify theme check --path sections/ buat ngecek sebagian).
  11. --verbose: log lebih detail.

Pemakaian umum:

shopify theme check
shopify theme check --path sections/
shopify theme check --auto-correct
shopify theme check --fail-level error --output json

Konfigurasi: .theme-check.yml

Taruh .theme-check.yml di root theme buat nimpa default, atau generate pakai shopify theme check --init. Semua setting opsional:

  1. root (string): kalau theme gak pakai struktur standar, path root tempat templates, sections, snippets berada. Kalau kamu generate kode dari src ke dist (transformasi file dari 54 Best Practices Umum > Transformasi File), arahkan ke dist.
  2. extends (string atau array): nyusun config dari config lain. Nilai ajaib: theme-check:all, theme-check:recommended, theme-check:theme-app-extension, plus file config lain atau modul pihak ketiga. Waktu banyak yang di-extend: object di-deep merge, array di-concat, yang terakhir di daftar menang.
  3. require (string atau array): import path CommonJS ke check kustom atau pihak ketiga.
  4. ignore (array): direktori/file yang dikecualikan, ndukung glob minimatch.
  5. Setting per check (object): enabled true/false, severity, ignore file/path khusus check itu, dan opsi lain check-nya. Check kustom harus diaktifin lewat ini. Nilai default opsi ada di referensi check.
# The directory where theme folders are located (optional)
root: dist
# Configuration files are extensible
extends:
  - theme-check:recommended # or theme-check:all, theme-check:theme-app-extension
  - '@acme/my-custom-checks/recommended.yml'
  - '../configs/.theme-check.yml'
# Paths to custom checks
require:
  - ./path/to/my_custom_check.js # path to file or module
  - '@acme/my-custom-checks'     # for node_modules checks
# Paths to ignore (don't lint those!)
ignore:
  - 'node_modules/**'
  - 'snippets/*-icon.liquid' # minimatch globs are supported
# Disable a check
TemplateLength:
  enabled: false
  severity: warning
  ignore:
    - templates/index.liquid
  # Configure options for a check
  max_length: 300
# Enable a custom check
MyCustomCheck:
  enabled: true
  severity: error

Satu jebakan nama opsi: nama setting check itu camelCase. Nama yang gak dikenali (misalnya threshold_in_bytes snake_case) cuma ngelog peringatan Unexpected setting dan diabaikan, jadi check-nya jalan dengan default tanpa kamu sadar.

❌ diabaikan diam-diam

AssetSizeJavaScript:
  enabled: true
  threshold_in_bytes: 10000

✅ camelCase

AssetSizeJavaScript:
  enabled: true
  thresholdInBytes: 10000

1. Severity

Severity nunjukin kepentingan relatif check buat fungsi dan optimasi theme: error, warning, info. Bisa diubah per check di config. Di CI, severity check yang gagal nentuin exit code: bawaannya Theme Check gagal (exit 1) kalau ada satu atau lebih masalah error, dan --fail-level ngubah ambangnya.

Config theme-check:recommended, theme-check:all, dan file dari --init nulis severity sebagai integer: error = 0, warning = 1, info = 2. Dua bentuk setara, tapi string lebih disukai karena lebih terbaca.

2. Nonaktifin Lewat Komentar Liquid

Buat pengecualian lokal tanpa nyentuh config, pakai komentar inline {% # ... %} dari 10 Tags Variabel dan Percabangan:

{% # theme-check-disable %}
{% assign x = 1 %}
{% # theme-check-enable %}

Semua check buat baris berikutnya:

{% # theme-check-disable-next-line %}
{% assign x = 1 %}

Check tertentu buat satu bagian:

{% # theme-check-disable UnusedAssign %}
{% assign x = 1 %}
{% # theme-check-enable UnusedAssign %}

Check tertentu buat baris berikutnya:

{% # theme-check-disable-next-line UnusedAssign %}
{% assign x = 1 %}

Banyak check dipisah koma, buat bagian maupun baris berikutnya:

{% # theme-check-disable UnusedAssign, UndefinedObject %}
{% assign x = 1 %}
{% echo y %}
{% # theme-check-enable UnusedAssign, UndefinedObject %}
{% # theme-check-disable-next-line UnusedAssign, UndefinedObject %}
{% assign x = y %}

Buat seluruh dokumen, taruh komentar disable di baris pertama tanpa enable:

{% # theme-check-disable UnusedAssign %}
{% assign x = 1 %}

Praktik yang disaranin: tiap disable dikasih alasan di komentar sebelahnya, biar orang berikutnya (termasuk kamu) tau kenapa pengecualiannya ada.

Check Performa

Dari sudut pandang performa, Theme Check nangkep masalah yang ngaruh ke semua Core Web Vitals, dan sebagian udah dibahas di bab 59–64:

  1. ParserBlockingScript: script tanpa defer/async (61 Performance JavaScript dan INP).
  2. RemoteAsset: aset dari domain eksternal, self-host lewat asset_url (64 Performance Navigasi dan Loading).
  3. CdnPreconnect: preconnect redundan ke CDN Shopify yang platform udah kirim.
  4. ImgWidthAndHeight: img tanpa width/height yang bikin layout shift (59 Performance Gambar dan LCP).
  5. PaginationSize: ukuran paginasi dalam rentang performan, default maxSize: 250 (58 Performance Liquid).
  6. AssetPreload: dorong filter Liquid (stylesheet_tag: preload: true) daripada tag HTML, biar dapat Early Hints.
  7. AssetSizeCSS dan AssetSizeJavaScript: file aset yang melebihi ambang, default 100.000 byte CSS dan 10.000 byte JavaScript. Keduanya ngukur ukuran mentah di disk (atau Content-Length aset remote), bukan minified/terkompresi, walaupun pesannya nyebut kompresi.

Dua yang terakhir bukan bagian theme-check:recommended, jadi gak jalan kecuali kamu aktifin. Mereka dihilangkan dari recommended, bukan di-set enabled: false, jadi nambahinnya ke .theme-check.yml yang ngaktifin:

AssetSizeCSS:
  enabled: true
  thresholdInBytes: 100000
AssetSizeJavaScript:
  enabled: true
  thresholdInBytes: 10000
PaginationSize:
  enabled: true
  maxSize: 250

Dan ingat dari 63 Performance Apps dan Pihak Ketiga: Theme Check gak bisa ngedeteksi manipulasi metrik atau nalar soal script yang ngakalin pengukuran, cuma pola yang dikenal.

Auto-correct

--auto-correct memperbaiki yang bisa diperbaiki secara mekanis: penggantian filter deprecated, file template yang hilang, object layout yang wajib (content_for_header/content_for_layout), dan sebagian syntax. Di tabel referensi, check yang ndukung ini ditandai “Yes” di kolom auto-correction: DeprecatedFilter, MissingTemplate, RequiredLayoutThemeObject, MatchingTranslations. Masalah performa, arsitektur, dan logika bisnis harus diperbaiki manual. Jalankan auto-correct sebelum commit, dan review diff-nya, karena “bisa diperbaiki otomatis” bukan berarti “pasti yang kamu mau”.

Alur Kerja

Theme Check itu garis pertahanan pertama, alat berbasis browser lapisan berikutnya:

  1. Saat development: jalankan sering, atau biarin VS Code extension nampilin inline.
  2. Sebelum commit: bersihin semua error dengan shopify theme check --auto-correct.
  3. Di CI/CD: blokir merge yang punya error, - run: shopify theme check dengan --fail-level sesuai kebijakan tim. Ini pasangan Lighthouse CI dari 68 Theme Inspector dan Lighthouse CI.
  4. Dengan alat lain: Lighthouse, WebPageTest, Theme Inspector buat analisis lebih dalam.

Pembagian perannya: Theme Check = analisis statis, nangkep error sebelum runtime, tiap commit. Theme Inspector = profil render Liquid nyata, waktu TTFB lambat. Lighthouse = metrik lab keseluruhan, sebelum launch dan audit berkala. WebPageTest = performa nyata dan waterfall, debug detail. Semuanya saling melengkapi, Theme Check duluan.

Migrasi dari Theme Check 1.x ke 2.x

Januari 2024, Theme Check 2.x diintegrasiin ke code editor admin, VS Code extension, dan CLI. Kalau kamu punya config atau alur kerja dari 1.x, ini yang berubah:

1. CLI

Dukungan kategori check dihapus: flag --category dan --exclude-category gak ada lagi. Alasannya nyederhanain API dan ngurangin noise --help. Kalau kamu butuh subset (misalnya cuma check performa), bikin config terpisah dan pakai kemampuan extends yang baru.

2. Konfigurasi

extends sekarang ndukung theme-check:all, theme-check:recommended, theme-check:theme-app-extension, plus daftar file config dan modul pihak ketiga. require gak ndukung check Ruby kustom lagi (Theme Check 1.x ditulis Ruby, 2.x TypeScript). Check kustom ditulis ulang di TypeScript ngikutin panduan “Creating your own checks” di repo theme-tools.

3. Tabel Kompatibilitas Check

Yang penting buat nulis ulang .theme-check.yml:

  1. Digabung: AssetSizeCSSStylesheetTag → AssetSizeCSS; ConvertIncludeToRender dan DeprecatedTags → DeprecatedTag; HtmlParsingError dan SyntaxError → LiquidHTMLSyntaxError; MatchingSchemaTranslations dan MatchingTranslations → MatchingTranslations; ParserBlockingJavaScript dan ParserBlockingScriptTag → ParserBlockingScript; ValidJson → JSONSyntaxError.
  2. Diganti nama: AssetUrlFilters → RemoteAsset.
  3. Dihapus (gak ada padanan di 2.x): DefaultLocale, DeprecatedGlobalAppBlockType, ImgLazyLoading, LiquidTag, MissingEnableComment, MissingRequiredTemplateFiles, NestedSnippet, RequiredDirectories, SchemaJsonFormat, SpaceInsideBraces, TemplateLength, UnusedSnippet (diganti OrphanedSnippet).
  4. Baru di 2.x: BlockIdUsage, DeprecatedFontsOnSectionsAndBlocks, DeprecatedFontsOnSettingsSchema, DuplicateContentForArguments, DuplicateRenderSnippetArguments, EmptyBlockContent, HardcodedRoutes, JSONMissingBlock, LiquidFreeSettings, MissingContentForArguments, MissingRenderSnippetArguments, OrphanedSnippet, SchemaPresetsBlockOrder, SchemaPresetsStaticBlocks, UnclosedHTMLElement, UniqueDocParamNames, UniqueStaticBlockId, UnrecognizedContentForArguments, UnrecognizedRenderSnippetArguments, UnsupportedDocTag, UnusedDocParam, ValidBlockTarget, ValidContentForArguments, ValidDocParamTypes, ValidLocalBlocks, ValidContentForArgumentTypes, ValidRenderSnippetArgumentTypes, ValidSchemaName, ValidSettingsKey, ValidStaticBlockType.
  5. Tetap sama: AppBlockValidTags, AssetPreload, AssetSizeAppBlockCSS, AssetSizeAppBlockJavaScript, AssetSizeCSS, AssetSizeJavaScript, CdnPreconnect, ContentForHeaderModification, DeprecateBgsizes, DeprecatedFilter, DeprecateLazysizes, ImgWidthAndHeight, MissingAsset, MissingTemplate, PaginationSize, RemoteAsset, RequiredLayoutThemeObject, TranslationKeyExists, UndefinedObject, UnknownFilter, UnusedAssign, ValidHTMLTranslation, ValidSchema.

Perhatiin arah perkembangannya: hampir semua check baru soal theme block, content_for, LiquidDoc, dan schema dari 28 Blocks, 29 Theme Blocks Mendalam, dan 07 Tools Lokal VS Code Extension, Prettier, LiquidDoc. Theme Check 2.x dibangun buat arsitektur theme generasi sekarang.

Halaman referensi buat check 1.x yang dihapus (default-locale, img-lazy-loading, liquid-tag, missing-enable-comment, missing-required-template-files, nested-snippet, required-directories, schema-json-format, space-inside-braces, template-length, unused-snippet, matching-schema-translations, deprecated-global-app-block-type) masih ada di dokumentasi, dan bakal kita sebut singkat di dua bab berikutnya biar lengkap.

Ringkasan

  1. Theme Check = linter statis Liquid dan JSON buat theme dan theme app extension: syntax, template hilang, variabel/snippet tak terpakai, tag deprecated, performa; error dengan link dokumentasi.
  2. Tiga jalur: CLI (shopify theme check), VS Code extension (inline), code editor admin (2.x sejak Januari 2024), plus Language Server buat editor lain dan check kustom TypeScript.
  3. Flag: --config, --fail-level (error/suggestion/style), --auto-correct, --init, --output json|text, --print, --list, --environment, --path, --verbose.
  4. .theme-check.yml: root, extends (theme-check:all|recommended|theme-app-extension + file/modul, deep merge, terakhir menang), require, ignore (glob), setting per check (enabled, severity, ignore, opsi camelCase, nama salah diabaikan diam-diam).
  5. Severity error/warning/info (= 0/1/2), gagal di error secara default, --fail-level buat CI.
  6. Komentar {% # theme-check-disable[-next-line] [Check1, Check2] %} … {% # theme-check-enable %}, di baris pertama buat seluruh file.
  7. Check performa: ParserBlockingScript, RemoteAsset, CdnPreconnect, ImgWidthAndHeight, PaginationSize (250), AssetPreload, dan opt-in AssetSizeCSS (100.000) / AssetSizeJavaScript (10.000) yang ngukur byte mentah.
  8. Auto-correct buat filter deprecated, template hilang, object layout wajib, MatchingTranslations; sisanya manual.
  9. Alur: development → --auto-correct sebelum commit → CI dengan --fail-level → Lighthouse/WebPageTest/Theme Inspector.
  10. 2.x: tanpa --category, extends fleksibel, tanpa check Ruby, banyak check digabung/diganti nama/dihapus/ditambah (mayoritas soal theme block, content_for, LiquidDoc).

Bab selanjutnya kita mulai referensi aturan satu per satu: dari AppBlockMissingSchema sampai LiquidTag, dengan apa yang dicek, kenapa penting, contoh salah dan benar, opsi, dan kapan boleh dinonaktifin.

Tampilan Grafik

Tautan Balik