Shopify Theme Check: Waarom een enkel bestandspad niet werkt (en wat je in plaats daarvan moet doen)

Het uitvoeren van shopify theme check ./sections/header.liquid doet niets nuttigs. De opdracht is syntactisch ongeldig in de huidige CLI: Theme Check accepteert geen positioneel bestandspadargument. De correcte scope-vlag is --path, en deze accepteert alleen een map, geen enkel bestand. Hier is precies wat werkt, waarom linting van enkele bestanden anders werkt dan je verwacht, en hoe je het correct in CI integreert.

Belangrijkste punten

• shopify theme check ./sections/header.liquid is ongeldig in de huidige Shopify CLI. Er zijn geen positionele bestandsargumenten.
• Gebruik --path om naar een map te wijzen (standaard is de huidige werkmap als weggelaten).
• Echte feedback voor enkele bestanden komt van de VS Code Language Server (themeCheck.onlySingleFileChecks), niet van de CLI.
• De standaard --fail-level is error, dus CI slaagt stil terwijl waarschuwingen zich opstapelen. Geef altijd --fail-level warning door.
• Vanaf Shopify CLI 4.0 (mei 2026) heeft de tool Node 22.12+ nodig en wordt automatisch bijgewerkt via je package manager buiten CI.

De exacte fout die de meeste ontwikkelaars maken

Je bewerkt sections/hero.liquid, je ziet een mogelijk lint-probleem en je typt:

shopify theme check ./sections/hero.liquid

Er gebeurt niets nuttigs. In de huidige CLI wordt dat positionele argument eenvoudigweg genegeerd of geeft een fout over een ontbrekende themamapmap.

Deze verwarring heeft een specifieke oorzaak: Theme Check 2.x (de Node-gebaseerde versie in Shopify CLI) verving de oudere Ruby gem, en de Ruby gem accepteerde wel een path-positioneel argument. Oudere tutorials, StackOverflow-antwoorden en blogposts geschreven voordat de Theme Check 2.x-migratie werd voltooid (begin 2024, waarbij --category en --exclude-category tegelijk werden verwijderd) tonen nog steeds de oude syntaxis. Die posts zijn nu fout.

Zoals bevestigd door Shopify's eigen CLI-referentie, is --path de enige manier om een run in te perken, en deze richt zich op een map, niet op een bestand.

Wat de vlag werkelijk doet

# Scope naar een specifieke themamapmap
shopify theme check --path ./my-theme

# Standaard naar de huidige werkmap
shopify theme check

# Los aanpasbare overtredingen automatisch op
shopify theme check -a

# Wijzig welk ernstniveau een exitcode zonder nul veroorzaakt
shopify theme check --fail-level warning

# Machinelesbare uitvoer (vlakke array per bestand)
shopify theme check -o json > results.json

# Vermeld elke actieve controle en de ernst ervan
shopify theme check --list

--path geeft Theme Check aan welke map als themawortels moet worden behandeld. Elk bestand in die map (templates, sections, snippets, layout, assets) wordt in een enkele doorgang gecontroleerd. Je kunt het niet beperken tot een enkel bestand op CLI-niveau.

Hoe je werkelijk een enkel bestand linted: de Language Server-benadering

De CLI is een tool voor hele thema's. Feedback voor enkele bestanden is de taak van de Shopify Liquid Language Server, die de Shopify Liquid VS Code-extensie voorziet.

De extensie stelt een instelling bloot genaamd themeCheck.onlySingleFileChecks. Wanneer ingesteld op true, schakelt het controles voor het hele thema uit (zoals UnusedSnippet en TranslationKeyExists) en controleert alleen welke bestanden momenteel in de editor zijn geopend. Dit maakt textDocument/didChange-controles ongeveer 125x sneller vergeleken met herkeuringen van het volledige thema bij elke toetsaanslag.

Voeg dit toe aan je VS Code-werkruimteinstellingen:

{
  "themeCheck.checkOnOpen": true,
  "themeCheck.checkOnChange": true,
  "themeCheck.checkOnSave": true,
  "themeCheck.onlySingleFileChecks": true
}

De afweging: je mist controles tussen bestanden tijdens het coderen. Het aanbevolen patroon is onlySingleFileChecks: true lokaal gebruiken voor snelheid, en vervolgens shopify theme check op het volledige thema in CI uitvoeren voordat je pusht.

Vergelijking: CLI versus Language Server voor feedback voor enkele bestanden

De --fail-level-gotcha die CI stil breekt

Dit verrast bijna elk team dat voor het eerst een lint-gate instelt.

Standaard is --fail-level ingesteld op error. Dat betekent dat een run die alleen waarschuwingen vindt met exitcode 0 afsluit. Je CI-job controleert de exitcode, ziet 0, markeert de stap groen, en die waarschuwingen stapelen zich stil op over tientallen PR's totdat iemand eindelijk een verouderd filter of een prestatieprobleem opmerkt dat maanden in productie zit.

Los het in een regel op:

shopify theme check --fail-level warning

Geaccepteerde niveaus, van meest tot minst streng:

• info
• suggestion
• style
• warning
• error (standaard)
• crash

Voor de meeste winkels is warning de juiste drempel. Het vangt echte problemen zonder louter stilistische suggesties tegen te houden.

Een productie-grade CI-patroon (GitHub Actions)

Hieronder staat het minimale, huidige patroon. Het gebruikt SHOPIFY_CLI_THEME_TOKEN voor niet-interactieve authenticatie en gated de build op Theme Check voordat je pusht.

name: Theme Lint and Deploy
on:
  push:
    branches: [main]
  pull_request:

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '22'

      - name: Install Shopify CLI
        run: npm install -g @shopify/cli @shopify/theme

      - name: Run Theme Check
        run: shopify theme check --path . --fail-level warning -o json > tc-results.json
        env:
          SHOPIFY_FLAG_STORE: ${{ secrets.SHOPIFY_STORE }}

      - name: Upload results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: theme-check-results
          path: tc-results.json

  deploy:
    needs: lint
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '22'
      - name: Install Shopify CLI
        run: npm install -g @shopify/cli @shopify/theme
      - name: Push theme
        run: shopify theme push --json --theme ${{ secrets.SHOPIFY_THEME_ID }}
        env:
          SHOPIFY_CLI_THEME_TOKEN: ${{ secrets.SHOPIFY_CLI_THEME_TOKEN }}
          SHOPIFY_FLAG_STORE: ${{ secrets.SHOPIFY_STORE }}

Merk op dat --strict op theme push alleen blokkeert op Theme Check-fouten, dus het doorgeven van --fail-level warning in de dedicated check-stap is de juiste gate, niet alleen vertrouwen op --strict.

Drie meer vlaggen die het waard zijn

• -a / --auto-correct: herstelt overtredingen die Theme Check kan oplossen zonder menselijk oordeel (spatiering in {% %}, ongebruikte toewijzingen). Voer dit lokaal uit, nooit blind in CI.
• --list: drukt elke ingeschakelde controle en de ernst ervan af. Nuttig wanneer een teamlid een .theme-check.yml toevoegt en je wilt de actieve regelset verifiëren voordat je de release doet.
• -C theme-check:all: schakelt elke beschikbare controle in, inclusief die uitgeschakeld in theme-check:recommended. Gebruik dit voor een periodieke grondige audit, niet als dagelijkse gate.

Wat veranderde in CLI 4.0 (mei 2026) wat je setup betreft

Als je pijplijn zich vreemd ging gedragen na mei 2026, is de oorzaak waarschijnlijk Shopify CLI 4.0. Twee dingen veranderden die theme check runs betreft:

1. Node 22.12+ is nu vereist. Pijpleidingen vastgepind aan Node 18 of 20 zullen bij de installatiestap mislukken.
2. Auto-upgrade wordt in CI overgeslagen. De CLI detecteert CI-omgevingen en werkt niet automatisch bij, wat het juiste gedrag is. Maar lokale projectinstallaties slaan ook auto-upgrade over, dus zorg ervoor dat je pijplijn expliciet de versie installeert die je wilt.

Als bonus clones theme init nu standaard Shopify's Skeleton-thema in plaats van Dawn. Dit betreft Theme Check-gedrag niet, maar het maakt uit als je een nieuw project in dezelfde pijplijn ondersteunt.

Veelgemaakte fouten in .theme-check.yml

Je .theme-check.yml-bestand zit in de themawortels en controleert welke controles lopen en met welke ernst. Een paar patronen die verwarring veroorzaken:

# Correct: uitbreiden van recommended, dan negeren
extend: theme-check:recommended

TemplateLength:
  enabled: false

UnusedAssign:
  severity: suggestion   # downgrade van warning

ParserBlockingJavaScript:
  enabled: true
  severity: error

• Gebruik niet --category of --exclude-category. Deze vlaggen werden in Theme Check 2.x verwijderd. Gebruik het YAML-bestand in plaats daarvan.
• De root-sleutel is alleen nodig als je themabestanden in een submap voorkomen (bijv. een build-outputmap zoals dist/). Je hebt het niet nodig voor een standaard Dawn- of Horizon-structuur.

Voor een breder overzicht van hoe Theme Check in een volledige Shopify-themawerkflow past, raadpleeg je mijn gids over Shopify-themeontwikkeling en Liquid best practices.

Als je dit als onderdeel van een grotere migratie of buildsysteem in een CI/CD-pijplijn bedradt, dekken de Shopify-themantwikkelaar-servicepagina hoe we geautomatiseerde kwaliteitsgates benaderen in clientprojecten.