Déboguer Shopify Liquid avec Claude

Points clés

• Pour déboguer Shopify Liquid avec Claude, collez trois choses : le modèle (template), l’erreur exacte et le schéma de l’objet. S’il en manque un, Claude devra deviner.
• La plupart des bugs Liquid sont silencieux. Un objet nil n’affiche rien, donc la page est blanche au lieu de déclencher une erreur.¹
• Les espaces (whitespace), l’ordre des filtres et la portée des boucles provoquent des bugs qui ressemblent à des problèmes de données mais qui sont en réalité des problèmes de syntaxe.²
• Claude est très performant sur la logique des templates et les JSON de schéma. Il l’est moins sur l’état en direct du thème et le code injecté par des applications qu’il ne peut pas voir.
• Validez chaque correctif avec la documentation de référence de Shopify Liquid avant de faire un push. Ne faites pas confiance aux réponses qui ne citent aucune source.

Pour déboguer Shopify Liquid avec Claude, vous devez lui fournir le même contexte qu’un développeur de thème senior demanderait. Liquid échoue silencieusement. Un objet manquant ne lève pas d’exception : il n’affiche rien.¹ Cela rend la catégorie de bugs « pourquoi cette section est-elle vide » difficile à analyser à partir d’une simple capture d’écran. Ce guide couvre les bugs Liquid courants, le contexte exact dont Claude a besoin, les structures de prompts pour isoler rapidement un bug, et les limites de la fiabilité de Claude.

Pour la configuration de la plateforme, consultez notre guide de configuration Shopify AI Toolkit avec Claude Code.

Pourquoi vous pouvez nous faire confiance

Jacques a plus de 15 ans d’expérience en développement et a travaillé avec des centaines de boutiques Shopify. Nous avons créé Fudge, l’opérateur IA pour les boutiques Shopify, qui a une note de 4.9 et un badge Built for Shopify. Nous débuggons du Liquid tous les jours, à la main et avec l’aide de l’IA.

Pourquoi les bugs Liquid sont difficiles à repérer

Liquid a été conçu pour échouer de manière sécurisée (fail safe) sur une boutique en ligne. Ce choix de conception est aussi ce qui le rend difficile à déboguer.

Seules deux valeurs sont « falsy » en Liquid : nil et false. Tout le reste - chaînes vides, zéro, tableaux (arrays) vides - est « truthy ».¹ Ainsi, une condition que vous pensez définir pour éviter l’absence de données passe souvent quand les données sont bien présentes, mais vides.

Une balise (tag) ou une sortie qui retourne nil n’affiche rien sur la page et est traitée comme false.¹ Il n’y a pas de stack trace (trace d’appels d’erreur). La section s’affiche simplement vide, et vous devez deviner quel objet a retourné nil.

C’est la raison principale pour laquelle déboguer du Liquid avec Claude fonctionne si bien quand c’est bien fait. Vous ne demandez pas à Claude d’attraper une exception. Vous lui demandez de déduire quel objet dans une chaîne s’est résolu en nil.

Le contexte dont Claude a besoin pour déboguer Liquid

Le meilleur indicateur d’un bon correctif est le contexte que vous collez. Donnez systématiquement ces trois éléments à Claude :

1. Le template ou le snippet. Collez le bloc complet, pas un fragment. Les bugs de scope se cachent dans les lignes que vous omettez.

2. L’erreur exacte ou le symptôme. « Translation missing: en.products.price » est beaucoup plus utile que « le prix est cassé ». S’il n’y a pas d’erreur visible, décrivez le symptôme exact : section vide, mauvais compte d’éléments, bloc dupliqué.

3. Le schéma de l’objet (schema). Indiquez à Claude avec quel objet vous travaillez - product, collection, cart - pour qu’il valide les noms des champs en fonction du vrai objet Shopify au lieu de les inventer.

Un prompt qui fonctionne :

Voici ma section. Le bloc de prix s'affiche vide sur certains produits
mais pas sur d'autres. L'objet est `product`. Qu'est-ce qui pourrait se résoudre en nil ?

[collez la section Liquid complète]

Sans le schéma, Claude peut faire référence à un champ qui n’existe pas pour cet objet. Sans le template complet, il ne peut pas voir la boucle qui a modifié la portée (scope) de la variable.

Les bugs Liquid les plus courants et comment les corriger

Objets nil et non définis (undefined)

Le bug Liquid le plus courant. Vous accédez à un attribut sur un objet qui est nil, et toute la sortie disparaît.¹

L’état empty (vide) compte aussi. Une ressource supprimée ou un paramètre sans valeur retourne un objet empty, que vous devez vérifier avant de lire les attributs.¹

Avant :

<span>{{ product.metafields.custom.subtitle.value }}</span>

Si ce metafield n’est pas défini, la chaîne se résout en nil et n’affiche rien. Demandez à Claude de mettre une protection :

Après :

{% if product.metafields.custom.subtitle != blank %}
  <span>{{ product.metafields.custom.subtitle.value }}</span>
{% endif %}

Utilisez ce prompt pour Claude : « Quels maillons de cette chaîne d’attributs peuvent être nil, et comment puis-je protéger chacun d’eux ? »

Problèmes de scope dans les boucles

Chaque boucle for possède un objet forloop, et il n’existe qu’à l’intérieur de la boucle : le lire à l’extérieur vous donnera nil.³ Les variables que vous déclarez avec assign à l’intérieur de la boucle sont différentes. Elles conservent la valeur de la dernière itération une fois la boucle terminée, ce qui est une cause fréquente d’erreurs de comptage. Les snippets appelés avec render ne peuvent pas du tout voir les variables du template parent.

Si votre décompte est erroné ou que votre logique pour le “dernier élément” échoue, le bug vient généralement du scope. Collez la boucle complète et demandez à Claude de tracer où chaque variable est définie et lue.

Contrôle du whitespace (espaces)

Liquid génère des espaces (whitespace) là où se trouvent vos balises. Les espaces superflus cassent les mises en page, alourdissent le HTML et peuvent même casser un JSON que vous générez en Liquid.

En ajoutant des tirets dans votre balise Liquid, vous pouvez supprimer le whitespace généré par Liquid au moment du rendu. Vous pouvez ajouter le tiret à la balise d’ouverture ou de fermeture pour nettoyer l’espace d’un seul côté.²

Avant :

{% for tag in product.tags %}
  {{ tag }}
{% endfor %}

Après :

{%- for tag in product.tags -%}
  {{- tag -}}
{%- endfor -%}

Demandez à Claude : « Ce bloc génère du whitespace superflu qui casse ma mise en page inline. Où dois-je placer les tirets de contrôle de whitespace ? »

Ordre d’enchaînement des filtres

Plusieurs filtres peuvent être appliqués sur une seule sortie, et ils sont exécutés de gauche à droite.⁴ L’ordre n’est pas qu’un détail esthétique. Un filtre qui attend une string plantera si un filtre précédent a déjà transformé la valeur en array.

Avant :

{{ product.title | split: ' ' | upcase }}

upcase attend une string, mais split a déjà renvoyé un array. Changez l’ordre pour qu’upcase s’exécute avant split : {{ product.title | upcase | split: ' ' }}.

Demandez à Claude : “Trace cette chaîne de filtres de gauche à droite. Quel type chaque filtre reçoit-il et renvoie-il ?”

Limites de pagination

Les boucles for sont plafonnées. Vous pouvez faire un maximum de 50 itérations avec une boucle for, et au-delà, vous aurez besoin de la balise paginate.³

La balise paginate divise un array sur plusieurs pages, et la valeur de page_size doit être comprise entre 1 et 250.⁵ Elle a aussi un plafond strict : vous pouvez paginer jusqu’au 25 000ème élément maximum, donc les arrays plus grands doivent être filtrés avant de paginer.⁵

Si la boucle sur une collection s’arrête silencieusement à 50 produits, il s’agit de la limite d’itération, pas d’un problème aux niveaux des données. Demandez à Claude d’envelopper (wrap) la boucle avec la balise paginate en utilisant un page_size valide.

Erreurs de schéma dans les sections et les blocs

Les bugs de schéma (schema) déclenchent des erreurs au moment de l’édition, et non au moment du rendu de la page, ce qui les rend bien plus faciles à repérer.

La balise {% schema %} ne doit contenir que du JSON valide. Les ID de paramètres (settings) doivent être uniques dans chaque section, tout comme les noms et types des blocs (blocks). Des ID en double, ou plus d’une balise {% schema %}, créent une erreur de syntaxe à l’édition du code du thème.⁶

Les blocs sont limités à 50 par section, limite qui peut être abaissée avec max_blocks. Les blocs statiques ne sont pas comptés dans cette limite.⁶

Collez le bloc contenant le schéma ainsi que l’erreur exacte renvoyée par l’éditeur. Demandez à Claude de valider le JSON et de vérifier l’unicité des ID. C’est l’une des tâches de débogage où Claude excelle parce que le schéma est autonome (il se suffit à lui-même) - l’état du thème en direct (live state) n’est pas nécessaire.

Pour créer des sections proprement dès le départ, consultez notre guide sur comment créer une section personnalisée dans Shopify.

Clés de traduction manquantes

Quand le filtre t ne trouve pas la clé dans le fichier de langue (locale) actif, il affiche Translation missing: [locale].[key] sur la page au lieu d’échouer silencieusement.⁷

Les clés utilisent la notation pointée (dot notation) qui correspond à la structure JSON, et elles doivent être entourées par des guillemets simples en Liquid.⁷ Une clé comme 'products.price' renvoie à l’entrée imbriquée products puis price dans la traduction JSON.

Avant :

{{ 'products.prise' | t }}

Une faute de frappe dans le chemin de la clé génère Translation missing: en.products.prise. Collez à la fois la ligne de code Liquid et le JSON de la locale correspondante ; Claude validera le chemin de la clé avec la structure du fichier.

Modèles de prompts pour isoler un bug

Réduisez la surface de recherche en premier

Ne collez pas l’intégralité d’un fichier en demandant : « Qu’est-ce qui ne va pas ». Reproduisez le bug dans le plus petit bloc qui continue d’échouer, puis collez-le. Un petit bout de code donné permet d’obtenir une réponse très précise.

Demandez à Claude de réfléchir avant de modifier

Prompt : « Avant de changer quoi que ce soit, liste les objets et les variables dans ce bloc qui pourraient être nil ou en dehors de la portée (out of scope). » Cela le force à faire un diagnostic ouvert, ce qui vous permet de revérifier (sanity check) ses hypothèses en fonction de vos connaissances de la boutique.

Donnez-lui la structure des données

Si un objet product n’a pas de variantes ou qu’un metafield n’est pas défini, dites-le-lui. Claude ne peut pas voir vos données réelles. Bien décrire la structure des données lui permet d’arrêter de deviner au hasard.

Une modification à la fois

Demandez-lui un correctif unique, testez-le, puis passez à un autre problème. Effectuer plusieurs corrections à la fois rend difficile de savoir laquelle a résolu le problème et laquelle en a créé un nouveau.

Pour en savoir plus sur la modification manuelle des thèmes en toute sécurité, lisez comment modifier un thème Shopify.

Valider un correctif avec la référence Liquid

Un correctif fait par une IA reste une simple hypothèse tant que vous ne l’avez pas vérifié. Deux bonnes habitudes s’imposent.

Vérifiez que chaque objet et de chaque filtre existe. Si Claude utilise un champ comme product.custom_price, revérifiez ce pointeur en consultant la référence (documentation) des objets Shopify Liquid. Les champs inventés retournent nil et réintroduiront ce même bug de champ vide qui vous a amené au début.¹

Vérifiez le comportement des filtres, pas seulement leurs noms. Assurez-vous que le filtre accepte le type de donnée input qu’il reçoit dans votre chaîne, car les filtres s’appliquent tous de la gauche vers la droite et chacun transmet sa sortie (output) au suivant.⁴

Le Shopify AI Toolkit peut valider le Liquid généré grâce à des schémas pré-intégrés, ce qui raccourcit cette boucle. Mais cela ne remplace pas pour autant une lecture du diff (des changements).

Les lacunes de Claude

Claude est très bon pour la logique de template, les chaînes de filtres et les schémas JSON. Mais il a des angles morts évidents.

L’état du thème en live. Dans un chat, Claude ne voit que ce que vous collez, donc un bug qui n’apparaît qu’avec un paramètre spécifique de l’éditeur de thème lui est invisible jusqu’à ce que vous décriviez cet état. Si vous récupérez le thème avec Shopify CLI dans Claude Code, il pourra lire les fichiers templates/*.json et settings_data.json, qui contiennent le placement des sections et les paramètres de l’éditeur, mais il ne pourra toujours pas voir le code que les apps injectent au runtime.

Le code injecté par les apps. De nombreux bugs sur le storefront proviennent du code qu’une app injecte au runtime via l’éditeur de thème ou content_for_header. Claude ne peut pas lire du code qu’on ne lui a jamais montré. Si un bug n’apparaît que lorsqu’une app est activée, cette app est un suspect que vous devez identifier vous-même.

Les bugs liés aux données. Une section qui plante uniquement sur des produits sans variantes, ou avec un metafield nil, est un problème de structure de données. Claude ne peut pas interroger votre catalogue. Il raisonne à partir des données que vous lui décrivez.

C’est là qu’un opérateur IA intégré directement à la boutique change la donne. Fudge, l’opérateur IA pour les boutiques Shopify, fonctionne à l’intérieur de Shopify et lit le code de votre thème, vos produits et votre marque avant de modifier quoi que ce soit, y compris les blocs ajoutés par vos apps et les modifications apportées par vos développeurs. Cela lui donne le contexte de l’état de la boutique qui manque à un assistant de code généraliste. Ses correctifs arrivent sous forme de brouillons avec une prévisualisation fonctionnelle, pour que vous puissiez les vérifier sur de vrais produits avant que les clients ne les voient, et le Shopify store editor conserve la version que chaque changement a remplacée au cas où vous devriez faire un rollback. Pour comprendre plus largement cette nouvelle façon de travailler, découvrez notre vision du développement Shopify AI-first.

Une boucle de débogage répétable

1. Reproduisez le bug dans le plus petit bloc défaillant.
2. Rassemblez le template, l’erreur exacte ou le symptôme, et le schéma de l’objet.
3. Demandez à Claude de diagnostiquer avant de modifier - listez ce qui pourrait être nil ou hors du scope.
4. Appliquez une seule correction et testez-la de manière isolée.
5. Validez chaque objet et filtre par rapport à la documentation Shopify Liquid.
6. Poussez en tant que thème non publié d’abord, jamais directement sur le thème en live.

Cette boucle transforme le modèle d’échec silencieux de Liquid d’un handicap en une simple checklist.

Pour des travaux plus poussés sur la logique personnalisée, consultez Comment ajouter de la logique Liquid personnalisée dans Shopify.

FAQ