Shopify Theme Check: Spezifische Dateien und Abschnitte mit der CLI prüfen

Um Shopify Theme Check auf spezifische Dateien oder Abschnitte auszuführen, hast du drei Optionen: Gib einen Pfad direkt an der CLI an, nutze Inline-Liquid-Kommentare, um Prüfungen für bestimmte Codeblöcke zu deaktivieren, oder konfiguriere ein Muster in deiner .theme-check.yml-Datei. Es gibt kein einzelnes Flag --only, das die Ausgabe auf eine Datei beschränkt, aber die Kombination dieser drei Ansätze gibt dir präzise Kontrolle darüber, was geprüft und was übersprungen wird.

Die wichtigsten Erkenntnisse

• shopify theme check ./sections/hero.liquid beschränkt die Prüfung auf einen spezifischen Dateipfad.
• Inline-Kommentare {% # theme-check-disable %} unterdrücken Prüfungen für einen benannten Liquid-Codeblock.
• .theme-check.yml ermöglicht es dir, ganze Glob-Muster (z. B. snippets/icon-*) dauerhaft zu ignorieren.
• Das Flag --config überschreibt deine Konfigurationsdatei spontan, was in CI-Pipelines hilfreich ist.
• Das veraltete Ruby-Gem Shopify/theme-check wurde im Juli 2024 archiviert. Der aktuelle Linter befindet sich in Shopify CLI über die Pakete @shopify/cli und @shopify/theme.

Warum gezieltes Linting wichtig ist (und woher die Verwirrung kommt)

Das Ausführen von shopify theme check auf einem großen Theme mit Hunderten von Liquid-Dateien erzeugt eine Flut von Warnungen. Die meisten Entwickler möchten nur die Datei linting, an der sie arbeiten, oder eine störende Prüfung für einen Abschnitt unterdrücken, ohne sie überall zu deaktivieren. Die CLI-Dokumentation behandelt dies, aber sie ist über drei separate Seiten verteilt, weshalb diese Frage immer wieder auftaucht.

Die gute Nachricht: Das Tooling ist wirklich flexibel. Sobald du weißt, welches Werkzeug du für welchen Fall einsetzt, ist der Workflow schnell.

Methode 1: Übergib einen Dateipfad als Positionsargument

Der direkteste Ansatz. Anstatt Theme Check gegen die ganze Theme-Root auszuführen, füge den relativen Pfad der Datei (oder des Ordners) an, den du prüfen möchtest:

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

Dies teilt dem Linter mit, dass nur diese Datei oder dieser Ordner analysiert werden soll. Ein wichtiger Vorbehalt: Theme-übergreifende Prüfungen werden teilweise unterdrückt, wenn du dich auf eine einzelne Datei beschränkst. Prüfungen, die ein Verständnis der ganzen Theme erfordern, wie UnusedSnippet oder TranslationKeyExists, sind im Einzeldatei-Modus deaktiviert, da sie die vollständige Theme lesen müssen, um aussagekräftige Ergebnisse zu liefern.

Für rein datei-Ebenen-Fehler (Liquid-Syntax, veraltete Filter, undefinierte Objekte, fehlende {% endschema %}-Tags) funktioniert die Einzeldatei-Eingrenzung perfekt.

Methode 2: Unterdrücke Prüfungen inline mit Liquid-Kommentaren

Wenn du einen umfassenden shopify theme check-Lauf behalten, aber eine bestimmte Prüfung für einen Codeabschnitt stummschalten möchtest, nutze Theme Checks integrierte Kommentar-Direktiven:

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

Um alle Prüfungen für einen Block zu deaktivieren:

{% # theme-check-disable %}
  {# ...alten Code, den du noch nicht migriert hast... #}
{% # theme-check-enable %}

Dieser Ansatz ist die richtige Wahl, wenn du an einem komplexen benutzerdefinierten Abschnitt arbeitest, eine ungeordnete Theme-Codebasis erbst oder Theme Check einem Projekt hinzufügst, das eine große Backlog von bereits vorhandenen Problemen hat, die du nicht in einem Durchgang beheben möchtest. Die Kommentare sind eng gefasst: Nichts außerhalb dieser Begrenzer ist betroffen.

Methode 3: Konfiguriere Ignore-Muster in .theme-check.yml

Für Pfade, die du dauerhaft ausschließen möchtest, ist die Konfigurationsdatei .theme-check.yml das richtige Werkzeug. Du kannst eine Starterdatei mit folgender Methode generieren:

shopify theme check --init

Bearbeite dann die Datei, um ignore-Glob-Muster unter spezifischen Prüfungen oder global hinzuzufügen:

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

Du kannst auch Schweregrade pro Prüfung (error, warning, info) festlegen, sodass bestimmte Probleme einen CI-Lauf fehlschlagen lassen, während andere nur als Information angezeigt werden. Standardmäßig gibt Theme Check Exit-Code 1 zurück, wenn mindestens ein Problem mit Schweregrad error erkannt wird. Nutze --fail-level, um diesen Schwellwert für deine Pipeline anzupassen:

shopify theme check --fail-level suggestion

Methode 4: Überschreibe die Konfiguration spontan mit --config

Wenn du mehrere Check-Profile verwaltest (eines streng, eines nachsichtig), lässt dich das Flag --config zwischen ihnen wechseln, ohne dass du eine Datei bearbeiten musst:

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

Diese integrierten Voreinstellungen decken die häufigsten Szenarien ab. theme-check:recommended ist die Standardeinstellung für die meisten Theme-Einreichungen; theme-check:all aktiviert jede verfügbare Prüfung und ist für eine gründliche Überprüfung vor der Veröffentlichung im Shopify Theme Store nützlich.

Was sich 2024 geändert hat: theme-check-Repository archiviert

Falls du ältere Lesezeichen oder Tutorials hast, die sich auf das eigenständige Ruby-Gem Shopify/theme-check beziehen, beachte, dass dieses Repository im Juli 2024 als schreibgeschützt archiviert wurde. Die gesamte aktive Entwicklung wurde in das Monorepo Shopify/theme-tools verlagert, und der Linter wird jetzt über die npm-Pakete @shopify/cli und @shopify/theme verteilt.

Zum Installieren oder Aktualisieren:

# macOS
brew upgrade shopify-cli

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

Ab Shopify CLI 4.0 aktualisiert sich die CLI automatisch selbst und nutzt den Package Manager, mit dem du sie installiert hast. In den meisten Fällen hast du also bereits die neueste Version.

Die VS-Code-Erweiterung (Shopify Liquid) bindet Theme Check auch ein und stellt eine Einstellung themeCheck.onlySingleFileChecks zur Verfügung. Wenn diese auf true gesetzt ist, prüft die Erweiterung nur die derzeit offene Datei und deaktiviert Theme-übergreifende Prüfungen für bessere Performance. Dies spiegelt das Single-File-Pfad-Verhalten der CLI wider und lohnt sich bei großen Themes, wo das vollständige Theme-Linting bei jedem Speichern den Editor verlangsamt.

Alles zusammen: Ein praktischer Workflow für die Abschnittsentwicklung

Hier ist das Muster, das beim Erstellen oder Debuggen eines benutzerdefinierten Liquid-Abschnitts gut funktioniert:

1. Starte einen Dev-Server: shopify theme dev --store your-store.myshopify.com
2. Bearbeite deinen Abschnitt: Nimm Änderungen an sections/your-section.liquid vor
3. Linte nur diese Datei: shopify theme check sections/your-section.liquid
4. Unterdrücke störende Prüfungen inline für bereits vorhandene Probleme, die du heute nicht behebst.
5. Führe eine vollständige Prüfung aus (shopify theme check), bevor du einen Pull Request öffnest oder in Produktion gehst.
6. Sperre CI auf Fehler mit --fail-level error, damit Warnungen Deployments nicht blockieren.

Dieser Ansatz hält deinen inneren Feedback-Loop schnell, während er trotzdem echte Fehler abfängt, bevor sie Kunden erreichen.

Das Halten deines Storefront-Codes sauber ist eine Schicht des Operations-Stacks. Die andere Schicht ist zu wissen, jeden Tag, welche Produkte kurz vor dem Ausverkauf stehen und dir echte Verkäufe kosten. Wenn du Bestände über Dutzende oder Hunderte von SKUs verwaltest, zeigt dir Stockcast: Inventory Forecast Prognosen für Lagerbestände, gereiht nach Dringlichkeit, mit transparenter und nachvollziehbarer Mathematik hinter jeder Empfehlung, sodass Bestellentscheidungen niemals Bauchgefühl sind.

Probiere Stockcast: Inventory Forecast im Shopify App Store aus

FAQ

Kann ich shopify theme check auf eine einzelne Liquid-Abschnittsdatei ausführen? Ja. Gib den Dateipfad als Positionsargument an: shopify theme check sections/your-section.liquid. Beachte, dass Theme-übergreifende Prüfungen (wie die Erkennung ungenutzter Snippets) deaktiviert sind, wenn du dich auf eine einzelne Datei beschränkst, da sie die vollständige Theme lesen müssen, um richtig zu funktionieren.

Wie deaktiviere ich eine spezifische Theme-Check-Regel für einen Codeblock, ohne sie überall auszuschalten? Nutze Inline-Liquid-Kommentar-Direktiven: {% # theme-check-disable CheckName %} vor dem Block und {% # theme-check-enable CheckName %} danach. Dies unterdrückt nur die benannte Prüfung innerhalb des abgegrenzten Blocks und lässt den Rest der Datei und Theme vollständig linting.

Was ist 2024 mit dem eigenständigen theme-check-Gem/CLI passiert? Shopify hat das Repository Shopify/theme-check im Juli 2024 archiviert und die gesamte aktive Entwicklung in das Monorepo Shopify/theme-tools verlagert. Theme Check wird jetzt als Teil von @shopify/cli verteilt und läuft über shopify theme check. Wenn du noch eine ältere Version nutzt, upgrade mit brew upgrade shopify-cli oder npm install -g @shopify/cli @shopify/theme.