Shopify Theme Check: Specifieke bestanden en secties controleren met de CLI

Om Shopify Theme Check op specifieke bestanden of secties uit te voeren, heb je drie opties: geef een padargument direct door aan de CLI, gebruik inline Liquid-opmerkingen om controles uit te schakelen voor doelgerichte codeblokken, of configureer een ignore patroon in je .theme-check.yml bestand. Er is geen enkele --only vlag die de uitvoer tot een bestand beperkt, maar door deze drie benaderingen te combineren krijg je nauwkeurige, chirurgische controle over wat wordt gecontroleerd en wat wordt overgeslagen.

Belangrijkste punten

• shopify theme check ./sections/hero.liquid beperkt de controle tot een specifiek bestandspad.
• Inline {% # theme-check-disable %} opmerkingen onderdrukken controles voor een benoemd Liquid-codeblok.
• .theme-check.yml laat je ignore hele glob-patronen (bijvoorbeeld snippets/icon-*) permanent uitsluiten.
• De --config vlag overschrijft je configuratiebestand ter plaatse, handig in CI-pipelines.
• De oude Shopify/theme-check Ruby gem werd in juli 2024 gearchiveerd; de huidige linter bevindt zich in Shopify CLI via de @shopify/cli en @shopify/theme pakketten.

Waarom gerichte controle van belang is (en waar de verwarring vandaan komt)

Het uitvoeren van shopify theme check op een groot thema met honderden Liquid-bestanden produceert een muur van waarschuwingen. De meeste ontwikkelaars willen slechts het bestand controleren waaraan zij werken, of een storende controle voor één sectie onderdrukken zonder deze overal uit te schakelen. De CLI-documentatie beantwoordt dit, maar het staat verspreid over drie aparte pagina's, daarom duikt deze vraag steeds weer op.

Het goede nieuws: de tooling is echt flexibel. Zodra je weet welke hendel je moet gebruiken voor welke situatie, is de workflow snel.

Methode 1: Geef een bestandspad op als positioneel argument

De meest directe aanpak. In plaats van Theme Check uit te voeren tegen de hele themahoofdmap, voeg je het relatieve pad van het bestand (of de map) toe dat je wilt controleren:

shopify theme check sections/custom-hero.liquid
shopify theme check snippets/product-card.liquid
shopify theme check sections/

Dit vertelt de linter om alleen dat bestand of die map te analyseren. Een belangrijk voorbehoud: thema-brede controles worden gedeeltelijk onderdrukt wanneer je het bereik tot één bestand beperkt. Controles die cross-file bewustzijn vereisen, zoals UnusedSnippet of TranslationKeyExists, worden uitgeschakeld in single-file modus omdat zij het volledige thema moeten lezen om zinvolle resultaten te geven.

Voor strikt bestandsniveau fouten (Liquid-syntaxis, verouderde filters, ongedefinieerde objecten, ontbrekende {% endschema %} tags), werkt single-file scoping perfect.

Methode 2: Controles inline onderdrukken met Liquid-opmerkingen

Wanneer je een brede shopify theme check run wilt behouden maar een specifieke controle voor één codesectie wilt stilzetten, gebruik je Theme Check's ingebouwde commentaardirectieven:

{% # theme-check-disable UnusedAssign %}
{% assign debug_mode = true %}
{% # theme-check-enable UnusedAssign %}

Om alle controles voor een blok uit te schakelen:

{% # theme-check-disable %}
  {# ...legacy code you haven't migrated yet... #}
{% # theme-check-enable %}

Deze aanpak is de juiste keuze wanneer je aan een complexe aangepaste sectie werkt, een rommelig themacodebase erft, of Theme Check aan een project toevoegt dat een groot backlog van reeds bestaande problemen heeft die je niet in één keer wilt oplossen. De opmerkingen zijn strak ingeperkt: niets buiten die scheidingslijnen wordt beïnvloed.

Methode 3: Configureer negeerpatronen in .theme-check.yml

Voor paden die je permanent wilt uitsluiten, is het .theme-check.yml configuratiebestand het juiste gereedschap. Je kunt een startbestand genereren met:

shopify theme check --init

Bewerk vervolgens het bestand om ignore globs onder specifieke controles of globaal toe te voegen:

TemplateLength:
  enabled: true
  max_length: 400
  ignore:
    - sections/legacy-homepage.liquid
    - snippets/icon-*

Je kunt ook per-controle ernstniveaus instellen (error, warning, info) zodat bepaalde problemen een CI-run doen mislukken terwijl anderen alleen als informatief worden gerapporteerd. Standaard geeft Theme Check exit code 1 terug wanneer minstens één probleem met ernst error wordt gedetecteerd. Gebruik --fail-level om deze drempel voor je pipeline aan te passen:

shopify theme check --fail-level suggestion

Methode 4: Configuratie overschrijven ter plaatse met --config

Als je meerdere controleprofielen onderhoudt (een strikt, een permissief), laat de --config vlag je ertussen wisselen zonder enig bestand te bewerken:

shopify theme check --config theme-check:recommended
shopify theme check --config theme-check:all

Deze ingebouwde voorinstellingen dekken de meest voorkomende scenario's. theme-check:recommended is de standaard voor de meeste themainzendingen; theme-check:all schakelt alle beschikbare controles in en is handig voor een grondige controle voordat je naar de Shopify Theme Store publiceert.

Wat veranderde in 2024: theme-check repo gearchiveerd

Als je oudere bladwijzers of tutorials hebt die verwijzen naar de standalone Shopify/theme-check Ruby gem, let op dat deze repository in juli 2024 gearchiveerd werd als alleen-lezen. Alle actieve ontwikkeling verplaatste zich naar de Shopify/theme-tools monorepo, en de linter wordt nu gedistribueerd via @shopify/cli en @shopify/theme npm pakketten.

Om te installeren of bij te werken:

# macOS
brew upgrade shopify-cli

# npm (global)
npm install -g @shopify/cli @shopify/theme

Vanaf Shopify CLI 4.0 werkt de CLI zichzelf automatisch bij met welk pakketbeheer je het ook hebt geïnstalleerd, dus in de meeste gevallen ben je al op de nieuwste versie.

De VS Code-extensie (Shopify Liquid) bundelt ook Theme Check en stelt een themeCheck.onlySingleFileChecks instelling beschikbaar. Wanneer ingesteld op true, controleert de extensie alleen het momenteel geopende bestand, en schakelt thema-brede controles uit voor prestaties. Dit weerspiegelt het single-file pad gedrag van de CLI en is het waard om in te schakelen voor grote thema's waar volledige thema-controle bij elke opslag de editor vertraagt.

Het samenbrengen: een praktische workflow voor sectie-ontwikkeling

Hier is het patroon dat goed werkt bij het bouwen of debuggen van een aangepaste Liquid sectie:

1. Start een dev-server: shopify theme dev --store your-store.myshopify.com
2. Bewerk je sectie: breng wijzigingen aan in sections/your-section.liquid
3. Controleer alleen dat bestand: shopify theme check sections/your-section.liquid
4. Onderdruk storende controles inline voor eventuele reeds bestaande problemen die je vandaag niet oplost.
5. Voer een volledige controle uit (shopify theme check) voordat je een pull request opent of naar productie pusht.
6. Gate CI op alleen fouten met behulp van --fail-level error zodat waarschuwingen implementaties niet blokkeren.

Deze aanpak houdt je inner feedback loop snel terwijl je toch echte fouten opvangt voordat zij je klanten bereiken.

Je winkelfrontcode schoon houden is één laag van de operationele stack. De andere laag is elke dag weten welke producten bijna uitverkocht zijn en je echte verkopen kosten. Als je voorraden over tientallen of honderden SKU's beheert, brengt Stockcast: Inventory Forecast voorspellingen van stockouts naar voren, gerangschikt op urgentie, met transparante, verklaarbare wiskunde achter elke aanbeveling, dus herordeningsbeslissingen zijn nooit een gok.

Probeer Stockcast: Inventory Forecast op de Shopify App Store

Veelgestelde vragen

Kan ik shopify theme check op één Liquid sectiebestand uitvoeren? Ja. Geef het bestandspad op als positioneel argument: shopify theme check sections/your-section.liquid. Let op dat thema-brede controles (zoals detectie van ongebruikte snippets) zijn uitgeschakeld wanneer je het bereik tot één bestand beperkt, omdat zij het volledige thema moeten lezen om correct te werken.

Hoe schakkel ik een specifieke Theme Check regel voor één codeblok uit zonder deze overal uit te schakelen? Gebruik inline Liquid commentaardirectieven: {% # theme-check-disable CheckName %} voor het blok en {% # theme-check-enable CheckName %} erna. Dit onderdrukt alleen die genoemde controle binnen het afgebakende blok en laat de rest van het bestand en thema volledig gecontroleerd.

Wat gebeurde er in 2024 met de standalone theme-check gem/CLI? Shopify archiveerde de Shopify/theme-check Ruby gem repository in juli 2024 en verplaatste alle actieve ontwikkeling naar de Shopify/theme-tools monorepo. Theme Check wordt nu gedistribueerd als onderdeel van @shopify/cli en draait via shopify theme check. Als je nog een oudere setup hebt, upgrade dan met brew upgrade shopify-cli of npm install -g @shopify/cli @shopify/theme.