Shopify Theme Check: Comment cibler des chemins de fichiers spécifiques et des fichiers Liquid de section

Shopify Theme Check ne peut pas accepter un chemin de fichier unique comme argument positionnel. Exécuter shopify theme check sections/hero.liquid ne validera pas uniquement ce fichier. L'outil valide toujours l'intégralité de l'arborescence du thème, mais plusieurs techniques supportées vous permettent de restreindre ce qui est vérifié, ce qui produit une erreur, et ce qui apparaît dans votre sortie. Voici chaque méthode qui fonctionne, y compris les changements introduits dans Theme Check 2.x.

Points clés à retenir

• shopify theme check sections/hero.liquid est une syntaxe invalide et produit une erreur dans Theme Check 2.x.
• --path restreint l'exécution à un sous-répertoire, pas à un seul fichier.
• La sortie JSON (-o json) passée dans jq est le seul moyen fiable de filtrer les résultats vers un seul fichier spécifique.
• .theme-check.yml peut ignorer des motifs glob entiers, supprimant le bruit des fichiers tiers ou générés.
• Les commentaires {% # theme-check-disable CheckName %} inline supprimaient des règles spécifiques dans n'importe quel fichier Liquid.
• Depuis CLI 4.0 (mai 2026), Theme Check nécessite Node 22.12+ et l'outil se met à jour automatiquement via votre gestionnaire de paquets.

Pourquoi il n'y a pas d'argument pour un seul fichier

Theme Check est un validateur de thème complet, pas un vérificateur de syntaxe fichier par fichier. Beaucoup de ses règles sont multi-fichiers par conception : MissingSnippet vérifie si un appel {% render %} correspond à un fichier réel ailleurs dans le thème, et UnusedAssign doit voir chaque modèle qui pourrait consommer une variable. L'exécuter contre un seul fichier isolé produirait des faux positifs sur exactement ces vérifications.

De par cette conception, la documentation officielle CLI de Shopify confirme que Theme Check est destiné à analyser l'arborescence complète du thème. Il n'existe pas de drapeau --file ou --only dans la CLI actuelle.

Méthode 1 : --path pour limiter un sous-répertoire

L'approximation supportée la plus proche de la validation d'un seul fichier est --path. Elle indique à Theme Check où se trouve la racine du thème, pas quel fichier vérifier. Mais vous pouvez le combiner avec une structure de répertoire créative durant le CI pour vous en rapprocher :

# Valide le thème entier depuis le répertoire de travail actuel (par défaut)
shopify theme check

# Valide un thème qui réside dans un sous-répertoire
shopify theme check --path ./my-theme

Si votre dossier sections est la seule partie du dépôt qui a changé dans une PR donnée, vous pouvez pointer --path vers une copie temporaire contenant uniquement les fichiers modifiés. C'est excessif pour la plupart des équipes, mais c'est utile quand un monorepo contient plusieurs thèmes.

Ce que --path ne fait PAS : il n'accepte pas un seul fichier comme sections/hero.liquid comme valeur. Passez un répertoire, pas un chemin de fichier.

Méthode 2 : sortie JSON passée dans jq pour le filtrage par fichier

C'est la méthode la plus pratique pour cibler un fichier sections/*.liquid spécifique dans un pipeline CI. Le drapeau -o json de Theme Check émet un tableau plat lisible par machine indexé par chemin de fichier. Passez-le dans jq pour extraire uniquement l'entrée qui vous intéresse :

# Exécute la vérification complète, produit JSON, puis filtre vers un fichier
shopify theme check -o json \
  | jq '.[] | select(.path == "sections/hero.liquid")'

Vous pouvez également affirmer un code de sortie non nul vous-même en fonction du résultat filtré :

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 a $ERRORS erreur(s)"
  exit 1
fi

Ce motif vous donne l'équivalent d'un contrôle par fichier dans votre travail GitHub Actions ou GitLab CI, sans avoir besoin d'un drapeau qui n'existe pas.

Méthode 3 : motifs d'ignorance .theme-check.yml

Si l'objectif est de faire taire un fichier ou un dossier spécifique plutôt que de le cibler, .theme-check.yml supporte des listes d'ignorance basées sur les globs par vérification. Vous pouvez également ignorer des répertoires entiers de toutes les vérifications en utilisant la clé ignore de haut niveau :

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

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

Générez une configuration de démarrage avec :

shopify theme check --init

C'est particulièrement utile quand vous avez des fichiers générés ou tiers (comme les snippets Replo) qui contiennent du Liquid délibérément fractionné qui déclencherait sinon LiquidHTMLParsingError sur theme dev.

Méthode 4 : commentaires de suppression inline à l'intérieur des fichiers Liquid de section

Pour les règles ponctuelles à l'intérieur d'un fichier de section spécifique, les commentaires Liquid inline vous permettent de désactiver et de réactiver n'importe quelle vérification nommée autour d'un bloc de code :

{%- comment -%} Supprime les faux positifs du motif de rendu vendor {%- endcomment -%}
{% # theme-check-disable UnusedAssign %}
{%- assign hero_context = section.settings.context -%}
{% # theme-check-enable UnusedAssign %}

Vous pouvez également supprimer une vérification pour le fichier entier en plaçant le commentaire de désactivation sur la première ligne :

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

Cette approche est visible dans l'examen du code (elle apparaît comme un diff d'une ligne) et n'affecte aucun autre fichier du thème.

Méthode 5 : onlySingleFileChecks VS Code pour le développement local

Si votre objectif est une rétroaction rapide dans votre éditeur tandis que vous modifiez activement un fichier de section, l'extension VS Code Shopify Liquid a un paramètre qui limite Theme Check au seul fichier ouvert :

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

Avec ceci activé, les vérifications multi-fichiers (comme MissingSnippet) sont ignorées et seules les règles d'un seul fichier s'exécutent sur l'onglet actif. Le dépôt officiel la décrit comme « excellente pour les performances si vous pouvez ignorer les vérifications qui s'étendent sur plusieurs fichiers lors du développement. » Exécutez shopify theme check complet dans CI pour attraper les problèmes multi-fichiers.

Comparaison : chaque méthode côte à côte

Exigences CLI 4.0 que vous ne devez pas négliger (mai 2026)

Depuis le lancement de CLI 4.0 en mai 2026, deux exigences ont changé qui affectent chaque pipeline CI exécutant Theme Check :

• Node 22.12+ est requis. Les anciennes versions de Node échoueront silencieusement ou produiront une sortie inattendue.
• L'outil se met à jour automatiquement via votre gestionnaire de paquets et ignore la mise à jour automatique dans CI par conception. Épinglez votre version dans package.json ou votre image CI explicitement.

Aussi bon à savoir : --category et --exclude-category ont été supprimés dans Theme Check 2.x (janvier 2024). Si vous trouvez des tutoriels plus anciens montrant ces drapeaux, ils ne fonctionnent plus. Utilisez -C theme-check:all pour exécuter explicitement chaque vérification disponible.

Motif de contrôle CI : la bonne façon d'exécuter Theme Check dans un pipeline

Voici la séquence de pipeline idiomatique recommandée par la propre documentation de Shopify :

# 1. Contrôle sur les erreurs (et les avertissements, que la plupart des équipes ignorent par défaut)
shopify theme check --fail-level warning

# 2. Pousse vers un thème de développement non publié pour l'aperçu
shopify theme push --unpublished --json

# 3. Promouvoir uniquement après examen manuel
shopify theme publish --theme <ID> --force

Deux erreurs courantes à éviter :

• Le --fail-level par défaut est error, ce qui signifie que les avertissements s'accumulent silencieusement et votre travail CI sort toujours 0. Passez --fail-level warning pour les bloquer.
• --strict sur theme push bloque également la poussée à moins que Theme Check ne passe, ce qui vous donne un deuxième filet de sécurité au moment du déploiement.

Pour les thèmes d'aperçu par PR, shopify theme push --development-context "pr-482" lie un thème de développement à un identifiant stable comme un numéro de PR.

Tout assembler : le workflow pratique pour les sections Liquid

Voici la séquence sur laquelle la plupart des équipes se retrouvent après avoir passé en revue ce qui précède :

1. Éditeur : activez onlySingleFileChecks dans VS Code pour une rétroaction rapide et in-file lors de l'écriture de Liquid de section.
2. Hook de pré-commit : exécutez shopify theme check --fail-level error contre le thème entier avant qu'une commit ne monte.
3. Portail de pull request CI : exécutez shopify theme check -o json | jq pour extraire et affirmer uniquement sur les fichiers de section modifiés.
4. Portail de déploiement CI : exécutez shopify theme push --strict afin que même si quelqu'un contourne l'étape 3, une poussée avec des erreurs soit bloquée.
5. Configuration : maintenez un .theme-check.yml avec des globs d'ignorance ciblés pour tout snippet généré ou vendor afin d'éviter que les faux positifs n'arrêtent le travail réel.

Vous avez besoin d'aide pour intégrer ceci à un pipeline réel? La page services de développeur de thème Shopify a du contexte sur la façon dont je le configure pour les projets des clients, et l'optimisation de vitesse Shopify couvre les vérifications de performance que Theme Check signale le plus souvent.