Shopify Theme Check: Hoe je specifieke bestandspaden en sections Liquid-bestanden richt

Shopify Theme Check accepteert geen enkel bestandspad als positional argument. Het uitvoeren van shopify theme check sections/hero.liquid zal niet alleen dat bestand controleren. Het gereedschap valideert altijd de volledige themaboom, maar verschillende ondersteunde technieken laten je beperken wat wordt gecontroleerd, wat afsluit met een fout, en wat in je uitvoer verschijnt. Hier is elke methode die werkt, inclusief wijzigingen geïntroduceerd in Theme Check 2.x.

Belangrijkste inzichten

• shopify theme check sections/hero.liquid is ongeldige syntaxis en sluit af met een fout in Theme Check 2.x.
• --path beperkt de uitvoering tot een submap, niet tot een enkel bestand.
• JSON-uitvoer (-o json) doorgegeven via jq is de enige betrouwbare manier om resultaten tot één specifiek bestand te filteren.
• .theme-check.yml kan hele globale patronen negeren, waardoor lawaai van externe of gegenereerde bestanden wordt onderdrukt.
• Inline {% # theme-check-disable CheckName %} opmerkingen onderdrukken specifieke regels in elk Liquid-bestand.
• Sinds CLI 4.0 (mei 2026) vereist Theme Check Node 22.12+ en werkt het gereedschap automatisch bij via je pakketbeheerder.

Waarom er geen enkel-bestandsargument is

Theme Check is een hele-thema linter, geen bestand-voor-bestand syntaxiscontrole. Veel van de regels zijn opzettelijk themaoverschrijdend: MissingSnippet controleert of een {% render %}-aanroep wordt opgelost naar een echt bestand elders in het thema, en UnusedAssign moet elk sjabloon zien dat een variabele kan gebruiken. Het uitvoeren ervan tegen één bestand geïsoleerd zou foutieve positieven produceren op precies die controles.

Vanwege dat ontwerp bevestigt Shopify's officiële CLI-documentatie dat Theme Check bedoeld is om de volledige themaboom te analyseren. Er is geen --file of --only vlag in de huidige CLI.

Methode 1: --path om een submap in te stellen

De dichtste ondersteunde benadering van controle op enkel bestand is --path. Het vertelt Theme Check waar de themabasis ligt, niet welk bestand moet worden gecontroleerd. Maar je kunt het combineren met een creatieve directorystructuur tijdens CI om dicht in de buurt te komen:

# Controleer het volledige thema van de huidige werkmap (standaard)
shopify theme check

# Controleer een thema in een submap
shopify theme check --path ./my-theme

Als je sections-map het enige deel van de repo is dat in een gegeven PR is gewijzigd, kun je --path naar een tijdelijke kopie wijzen die alleen de gewijzigde bestanden bevat. Dit is overdreven voor de meeste teams, maar nuttig wanneer een monorepo meerdere thema's bevat.

Wat --path NIET doet: het accepteert geen enkel bestand zoals sections/hero.liquid als waarde. Geef een map door, geen bestandspad.

Methode 2: JSON-uitvoer doorgegeven via jq voor filteren per bestand

Dit is de meest praktische methode om gericht een specifiek sections/*.liquid-bestand in een CI-pijplijn te richten. De vlag -o json van Theme Check geeft een machine-leesbare platte array uit, geindexeerd op bestandspad. Geef dat door via jq om alleen het item dat je nodig hebt te extraheren:

# Voer de volledige controle uit, output JSON, filter dan tot één bestand
shopify theme check -o json \
  | jq '.[] | select(.path == "sections/hero.liquid")'

Je kunt ook zelf een afsluitcode verschillend van nul beweringen op basis van het gefilterde resultaat:

ERRORS=$(shopify theme check -o json \
  | jq '[.[] | select(.path == "sections/hero.liquid") | .offenses[] | select(.severity == "error")] | length')

if [ "$ERRORS" -gt 0 ]; then
  echo "hero.liquid heeft $ERRORS fout(en)"
  exit 1
fi

Dit patroon geeft je het equivalent van per-bestand gatekeeping in je GitHub Actions of GitLab CI job, zonder dat je een vlag nodig hebt die niet bestaat.

Methode 3: .theme-check.yml negeerpatronen

Als het doel is om een specifiek bestand of map tot zwijgen te brengen in plaats van het gericht aan te richten, ondersteunt .theme-check.yml negeerlijsten op basis van globale patronen per controle. Je kunt ook hele mappen van alle controles negeren met behulp van de top-level ignore-sleutel:

# .theme-check.yml
TemplateLength:
  enabled: true
  ignore:
    - sections/legacy-*
    - snippets/vendor-*

UnusedAssign:
  enabled: true
  ignore:
    - snippets/replo-*

Genereer een startconfiguratie met:

shopify theme check --init

Dit is vooral nuttig wanneer je gegenereerde of externe bestanden hebt (zoals Replo-snippets) die opzettelijk gesplitste Liquid bevatten die anders LiquidHTMLParsingError zou activeren op theme dev.

Methode 4: Inline suppressie-opmerkingen in sections Liquid

Voor eenmalige regels in een specifiek sectionbestand laat je Liquid inline opmerkingen je elke benoemde controle rond een codeblok uitschakelen en opnieuw inschakelen:

{%- comment -%} Onderdruk foutpositief van leveranciersrenderpatroon {%- endcomment -%}
{% # theme-check-disable UnusedAssign %}
{%- assign hero_context = section.settings.context -%}
{% # theme-check-enable UnusedAssign %}

Je kunt ook een controle voor het hele bestand onderdrukken door de disable-opmerking op de eerste regel te plaatsen:

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

Deze benadering is zichtbaar in code review (het verschijnt als een diff van één regel) en beïnvloedt geen ander bestand in het thema.

Methode 5: VS Code onlySingleFileChecks voor lokale ontwikkeling

Als je doel snelle feedback in je editor is terwijl je actief een sectionbestand bewerkt, heeft de Shopify Liquid VS Code-extensie een instelling die Theme Check beperkt tot alleen het open bestand:

// .vscode/settings.json
{
  "themeCheck.onlySingleFileChecks": true
}

Als dit aan staat, worden themaoverschrijdende controles (zoals MissingSnippet) overgeslagen en worden alleen controles op enkel bestand uitgevoerd op het actieve tabblad. De officiële repo beschrijft het als "geweldig voor prestaties als je controles die meerdere bestanden omvatten tijdens ontwikkeling kunt negeren." Voer de volledige shopify theme check uit in CI om de themaoverschrijdende problemen op te vangen.

Vergelijking: elke methode naast elkaar

CLI 4.0-vereisten die je niet mag negeren (mei 2026)

Sinds CLI 4.0 in mei 2026 is uitgebracht, zijn twee vereisten gewijzigd die elke CI-pijplijn met Theme Check beïnvloeden:

• Node 22.12+ is vereist. Oudere Node-versies zullen stillekletspraat uitvoeren of onverwachte uitvoer produceren.
• Het gereedschap werkt automatisch bij via je pakketbeheerder en slaat auto-upgrade in CI opzettelijk over. Zet je versie vast in package.json of je CI-image expliciet.

Ook vermeldenswaardig: --category en --exclude-category werden verwijderd in Theme Check 2.x (januari 2024). Als je oudere tutorials vindt die die vlaggen tonen, werken ze niet meer. Gebruik -C theme-check:all om elke beschikbare controle expliciet uit te voeren.

CI gate-patroon: de juiste manier om Theme Check in een pijplijn uit te voeren

Hier is de idiomatische pijpijnvolgorde aanbevolen door Shopify's eigen documentatie:

# 1. Gatekeep fouten (en waarschuwingen, die de meeste teams standaard negeren)
shopify theme check --fail-level warning

# 2. Push naar een niet-gepubliceerd ontwikkelingthema voor voorbeeld
shopify theme push --unpublished --json

# 3. Promoot alleen na handmatige beoordeling
shopify theme publish --theme <ID> --force

Twee veel voorkomende fouten om te vermijden:

• De standaard --fail-level is error, wat betekent dat waarschuwingen op de achtergrond accumuleren en je CI-job nog steeds afsluit met 0. Geef --fail-level warning door om erop te blokken.
• --strict op theme push blokkeert ook de push tenzij Theme Check slaagt, wat je een tweede veiligheidsnet op implementatietijd geeft.

Voor per-PR preview-thema's bindt shopify theme push --development-context "pr-482" een ontwikkelingthema aan een stabiele identifier zoals een PR-nummer.

Het samenvoegen: de praktische workflow voor sections Liquid

Hier is de volgorde waar de meeste teams uiteindelijk op uitkomen na het bovenstaande:

1. Editor: schakel onlySingleFileChecks in VS Code in voor snelle, in-bestandsfeedback bij het schrijven van section Liquid.
2. Pre-commit hook: voer shopify theme check --fail-level error uit tegen het hele thema voordat een commit gaat.
3. CI pull request gate: voer shopify theme check -o json | jq uit om alleen de gewijzigde sectionbestanden te extraheren en te beweringen.
4. CI deploy gate: voer shopify theme push --strict uit zodat zelfs als iemand stap 3 omzeilt, een push met fouten wordt geblokkeerd.
5. Config: onderhoud een .theme-check.yml met gerichte negeerglobs voor gegenereerde of leveranciersnippets om foutieve positieven te voorkomen die echte werk stoppen.

Hulp nodig bij het bedraden van dit in een echte pijplijn? De pagina Shopify theme developer services heeft context over hoe ik dit voor klantprojecten instelde, en Shopify speed optimization behandelt de prestatiecontroles die Theme Check het meest markeert.