Shopify Theme Check Fichiers et Sections Spécifiques avec la CLI

Pour exécuter Shopify Theme Check sur des fichiers ou sections spécifiques, vous avez trois options : transmettre un argument de chemin directement à la CLI, utiliser des commentaires Liquid inline pour désactiver les vérifications pour des blocs de code ciblés, ou configurer un modèle ignore dans votre fichier .theme-check.yml. Il n'existe pas de flag --only unique qui restreint la sortie à un seul fichier, mais en combinant ces trois approches, vous obtenez un contrôle précis et chirurgical sur ce qui est linter et ce qui est ignoré.

Points clés à retenir

• shopify theme check ./sections/hero.liquid restreint l'exécution à un chemin de fichier spécifique.
• Les commentaires inline {% # theme-check-disable %} suppriment les vérifications pour un bloc de code Liquid nommé.
• .theme-check.yml vous permet d'ignore des modèles glob entiers (par exemple, snippets/icon-*) de manière permanente.
• Le flag --config remplace votre fichier de configuration à la volée, utile dans les pipelines CI.
• Le gem Ruby hérité Shopify/theme-check a été archivé en juillet 2024. Le linter actuel se trouve à l'intérieur de Shopify CLI via les packages @shopify/cli et @shopify/theme.

Pourquoi la linting ciblée est importante (et d'où vient la confusion)

Exécuter shopify theme check sur un grand thème contenant des centaines de fichiers Liquid produit un mur d'avertissements. La plupart des développeurs veulent linter uniquement le fichier sur lequel ils travaillent, ou supprimer une vérification bruyante pour une section sans la désactiver partout. La documentation CLI répond à cette question, mais elle est dispersée sur trois pages distinctes, ce qui explique pourquoi cette question revient constamment.

La bonne nouvelle : les outils sont véritablement flexibles. Une fois que vous savez quel levier actionner pour chaque cas d'usage, le flux de travail est rapide.

Méthode 1 : Transmettre un chemin de fichier comme argument positionnel

L'approche la plus directe. Au lieu d'exécuter Theme Check sur la racine du thème entier, ajoutez le chemin relatif du fichier (ou du répertoire) que vous souhaitez vérifier :

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

Cela indique au linter d'analyser uniquement ce fichier ou ce dossier. Une mise en garde importante : les vérifications de thème complet sont partiellement supprimées lorsque vous délimitez à un seul fichier. Les vérifications qui nécessitent une sensibilisation inter-fichiers, telles que UnusedSnippet ou TranslationKeyExists, sont désactivées en mode fichier unique car elles ont besoin de lire le thème entier pour produire un résultat significatif.

Pour les erreurs strictement au niveau des fichiers (syntaxe Liquid, filtres obsolètes, objets non définis, balises {% endschema %} manquantes), le délimitation à un seul fichier fonctionne parfaitement.

Méthode 2 : Supprimer les vérifications inline avec des commentaires Liquid

Lorsque vous souhaitez conserver une exécution shopify theme check large mais silencier une vérification spécifique pour une section de code, utilisez les directives de commentaire intégrées de Theme Check :

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

Pour désactiver toutes les vérifications pour un bloc :

{% # theme-check-disable %}
  {# ...code hérité que vous n'avez pas encore migré... #}
{% # theme-check-enable %}

Cette approche est le bon choix lorsque vous itérez sur une section personnalisée complexe, que vous héritez d'une base de code de thème désordonnée, ou que vous ajoutez Theme Check à un projet qui a un grand arriéré de problèmes préexistants que vous n'êtes pas prêt à corriger en une seule fois. Les commentaires sont étroitement délimités : rien en dehors de ces délimiteurs n'est affecté.

Méthode 3 : Configurer les modèles d'ignorance dans .theme-check.yml

Pour les chemins que vous souhaitez exclure définitivement, le fichier de configuration .theme-check.yml est le bon outil. Vous pouvez générer un fichier de démarrage avec :

shopify theme check --init

Ensuite, modifiez le fichier pour ajouter des globs ignore sous des vérifications spécifiques ou globalement :

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

Vous pouvez également définir des niveaux de sévérité par vérification (error, warning, info) afin que certains problèmes fassent échouer une exécution CI tandis que d'autres sont signalés comme informationnels uniquement. Par défaut, Theme Check retourne le code de sortie 1 lorsqu'au moins un problème avec la sévérité error est détecté. Utilisez --fail-level pour ajuster ce seuil pour votre pipeline :

shopify theme check --fail-level suggestion

Méthode 4 : Remplacer la configuration à la volée avec --config

Si vous maintenez plusieurs profils de vérification (un strict, un permissif), le flag --config vous permet de basculer entre eux sans modifier aucun fichier :

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

Ces présets intégrés couvrent les scénarios les plus courants. theme-check:recommended est le défaut pour la plupart des soumissions de thème ; theme-check:all active chaque vérification disponible et est utile pour un audit complet avant la publication sur le Shopify Theme Store.

Ce qui a changé en 2024 : dépôt theme-check archivé

Si vous avez des signets plus anciens ou des tutoriels référençant le gem Ruby Shopify/theme-check autonome, notez que ce dépôt a été archivé en lecture seule en juillet 2024. Tout le développement actif a migré vers le monodépôt Shopify/theme-tools, et le linter est maintenant distribué via les packages npm @shopify/cli et @shopify/theme.

Pour installer ou mettre à jour :

# macOS
brew upgrade shopify-cli

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

À partir de Shopify CLI 4.0, la CLI se met à jour automatiquement en utilisant le gestionnaire de packages avec lequel vous l'avez installée, donc dans la plupart des cas, vous êtes déjà à jour.

L'extension VS Code (Shopify Liquid) regroupe également Theme Check et expose un paramètre themeCheck.onlySingleFileChecks. Lorsqu'il est défini à true, l'extension vérifie uniquement le fichier actuellement ouvert, désactivant les vérifications de thème complet pour la performance. Cela reflète le comportement du chemin de fichier unique de la CLI et vaut la peine d'être activé sur les grands thèmes où la linting de thème complet à chaque sauvegarde ralentit l'éditeur.

Assembler tout cela : un flux de travail pratique pour le développement de sections

Voici le modèle qui fonctionne bien lors de la création ou du débogage d'une section Liquid personnalisée :

1. Démarrez un serveur de développement : shopify theme dev --store your-store.myshopify.com
2. Modifiez votre section : apportez des modifications à sections/your-section.liquid
3. Linter uniquement ce fichier : shopify theme check sections/your-section.liquid
4. Supprimez les vérifications bruyantes inline pour tous les problèmes préexistants que vous ne corrigez pas aujourd'hui.
5. Exécutez une vérification complète (shopify theme check) avant d'ouvrir une demande d'extraction ou de pousser vers la production.
6. Limitez la CI aux erreurs uniquement en utilisant --fail-level error afin que les avertissements ne bloquent pas les déploiements.

Cette approche maintient votre boucle de rétroaction interne rapide tout en attrapant les erreurs réelles avant qu'elles ne atteignent les clients.

Maintenir votre code de vitrine propre est une couche de la pile d'opérations. L'autre couche consiste à savoir, chaque jour, quels produits sont sur le point de s'épuiser et vous coûter des ventes réelles. Si vous gérez l'inventaire sur des dizaines ou des centaines de SKU, Stockcast: Inventory Forecast affiche les prédictions de rupture de stock classées par urgence avec des mathématiques transparentes et explicables derrière chaque recommandation, afin que les décisions de réapprovisionnement ne soient jamais une supposition basée sur l'instinct.

Essayez Stockcast: Inventory Forecast sur le Shopify App Store

FAQ

Puis-je exécuter shopify theme check sur un fichier de section Liquid unique ? Oui. Transmettez le chemin du fichier comme argument positionnel : shopify theme check sections/your-section.liquid. Notez que les vérifications de thème complet (telles que la détection de snippets inutilisés) sont désactivées lors du délimitation à un seul fichier, car elles nécessitent de lire le thème entier pour fonctionner correctement.

Comment désactiver une règle Theme Check spécifique pour un bloc de code sans la désactiver partout ? Utilisez les directives de commentaire Liquid inline : {% # theme-check-disable CheckName %} avant le bloc et {% # theme-check-enable CheckName %} après. Cela supprime uniquement cette vérification nommée dans le bloc délimité et laisse le reste du fichier et du thème entièrement linté.

Que s'est-il passé avec le gem/CLI theme-check autonome en 2024 ? Shopify a archivé le dépôt du gem Ruby Shopify/theme-check en juillet 2024 et a déplacé tout le développement actif vers le monodépôt Shopify/theme-tools. Theme Check est maintenant distribué dans le cadre de @shopify/cli et s'exécute via shopify theme check. Si vous utilisez une ancienne configuration, mettez à jour avec brew upgrade shopify-cli ou npm install -g @shopify/cli @shopify/theme.