Déboguer Shopify Liquid avec Claude

Principaux points à retenir

• Pour déboguer (debugger) Shopify Liquid avec Claude, collez trois éléments : le template, l’erreur exacte et le schéma de l’objet (object schema). S’il en manque un, Claude va simplement deviner.
• La plupart des bugs Liquid sont silencieux. Un objet nil n’affiche rien, donc la page s’affiche vide au lieu de planter.¹
• Le whitespace (les espaces), l’ordre des filtres et la portée (scope) des boucles provoquent des bugs qui ressemblent à des problèmes de données mais sont des problèmes de syntaxe.²
• Claude est très fort sur la logique des templates et la structure JSON des schémas. Il a cependant des lacunes sur l’état en direct du thème (live theme state) et le code injecté par des applications qu’il ne peut pas voir.
• Validez chaque correctif avec la référence Shopify Liquid avant de pusher. Ne faites pas confiance à une réponse qui ne cite aucune source.

Pour déboguer Shopify Liquid avec Claude, vous devez lui fournir le même contexte que demanderait un développeur de thème senior. 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 vide » difficile à analyser à partir d’une simple capture d’écran. Ce guide couvre les bugs Liquid les plus courants, le contexte exact dont Claude a besoin, les modèles de prompt qui permettent d’isoler rapidement un bug, et les limites où Claude cesse d’être fiable.

Pour la configuration de la plateforme, consultez notre guide de configuration du 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 - un page builder et éditeur de boutique Shopify natif IA avec une note de 5,0 et un badge Built for Shopify. Nous déboguons du Liquid au quotidien, que ce soit à la main ou 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

Les variables définies à l’intérieur d’une boucle for, ainsi que l’objet forloop lui-même, appartiennent à la boucle. Chaque boucle for possède un objet forloop associé qui contient des informations sur la boucle.³ Essayer de le lire en dehors de la boucle vous retournera nil, et non la dernière valeur.

Si votre décompte est faux ou si votre logique de « dernier élément » saute, 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

On peut utiliser plusieurs filtres sur une même sortie, et ils s’appliquent de gauche à droite.⁴ L’ordre n’est pas purement esthétique. Un filtre qui attend une string (chaîne de caractères) cassera si un filtre précédent a déjà transformé la valeur en un array (tableau).

Avant :

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

upcase attend une string, mais split a déjà retourné un array. Réorganisez l’ordre, ou utilisez le filtre default pour gérer une entrée nil au début de la chaîne.

Demandez à Claude : « Retrace cette chaîne de filtres de gauche à droite. Quel type (de donnée) chaque filtre reçoit et retourne-t-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 des modèles (templates), la chaîne de filtres et les schémas JSON. Mais il a de vrais angles morts.

L’état en direct du thème (live theme state). Claude ne peut pas savoir dans quel modèle se trouve une section, ni ce que le marchand a configuré dans l’éditeur de thème, ni même quels blocs d’application sont actifs. Un bug qui ne survient qu’avec un paramètre spécifique lui sera invisible. Vous devrez décrire tout cet état.

Le code injecté par des apps. De nombreux bugs de l’interface découlent de certaines injections de code par d’autres applications lors de l’exécution (runtime) - parfois dans l’éditeur ou alors par l’apport d’un content_for_header. Claude ne peut pas lire des éléments de code qui ne lui ont jamais été donnés. Si un bug ne se manifeste qu’avec une certaine app activée, c’est que l’application est un suspect que vous devrez identifier par vous-même.

Les bugs liés aux données. Une section qui se casse l’affichage que sur un produit en particulier (sans variante), ou causé par un metafield qui retourne nil, concerne uniquement votre structure de données. Claude ne peut pas faire de recherches et consulter votre catalogue. Il raisonne sur les données que vous lui décrirez.

C’est là qu’un système d’IA intégré directement à l’intérieur d’une boutique change tout l’aspect de création. Parce que Fudge travaille pour vous de l’intérieur de Shopify, parce qu’il comprend tous les produits, la contexture de votre commerce, il opère un rôle clé sur des choses qu’un simple outil de code ne maîtrise pas. Si vous souhaitez en lire davantage du changement lié au monde d’un tel fonctionnement, nous avons fait notre avis sur le métier de développeur IA First Shopify.

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 (object schema).
3. Demandez à Claude d’établir le diagnostique avant d’éditer ou de corriger le code - listez-lui ce qui pourrait être un nil ou une portée de boucle invalide (out of scope).
4. Appliquez un seul correctif et testez votre avancement.
5. Validez chaque nouvel objet et vos nouveaux filtres au regard de la référence officielle Shopify Liquid.
6. Pushez le résultat dans un thème de test non publié, ne modifiez jamais directement en live.

C’est la boucle qui transforme les échecs silencieux de Liquid - et leur cauchemar - en une parfaite petite checklist facile.

Si vous souhaitez consulter l’intégration en plus complexe, alors accédez à comment ajouter une logique complète en Liquid Shopify.

Résumé

Déboguer du code en Shopify Liquid avec Claude se résume toujours à son contexte de situation et à son diagnostic ou validation. Collez le template complet en question avec l’erreur rencontrée et son schéma d’objet. De là : Claude devinera quelles chaînes de variables ont un défaut nil, vos défauts sur les portées (scope) de boucles et l’ordre des filtres, mais également votre analyse du JSON. Prenez garde de bien isoler les aspects qu’il ne peut pas comprendre, ou deviner - l’état du thème direct sur le site, ou alors votre catalogue et son architecture cachée. Validez l’intégralité d’une correction Shopify via le guide officiel de Liquid tout cela avant de le déployer.

Mais s’il est plus simple à vos yeux de simplement refuser de développer avec la logique de Liquid pour une gestion au long terme : modifiez et créez votre plateforme boutique d’un constructeur e-commerce et IA dotés des meilleures compréhensions propres.

FAQ