Pourquoi Horizon n'a pas main-cart-items.liquid (et comment personnaliser cart-items-component à la place)

Horizon n'a pas de fichier de section main-cart-items.liquid. Ce fichier existe dans Dawn, pas dans Horizon. Dans Horizon, le rendu des articles du panier est géré par main-cart.liquid (la section) avec le cart-items-component, un élément web personnalisé. Personnaliser le panier signifie donc travailler dans cette architecture de composant web plutôt que d'éditer une section Liquid classique.

Points clés à retenir

• Horizon a remplacé le pattern monolithique main-cart-items.liquid par un composant web autonome cart-items-component.
• Éditer directement les fichiers principaux de Horizon sera écrasé lors de la prochaine mise à jour du thème (Horizon publie des versions hebdomadaires).
• Les attributs du panier vont dans main-cart-footer.liquid ; les propriétés des articles sont rendues via l'itération cart.items à l'intérieur de main-cart.liquid.
• Le chemin de personnalisation sûr est : nouveaux fichiers de blocs dans blocks/, fichiers de section préfixés, et une branche upstream GitHub pour fusionner les mises à jour de Shopify proprement.
• Les applications construites pour l'ancienne architecture Online Store 2.0 cassent souvent sur le panier Horizon car les composants web s'exécutent à l'intérieur du Shadow DOM.

Pourquoi le fichier que vous cherchez n'existe pas

La documentation Shopify et d'innombrables tutoriels font référence à main-cart-items.liquid parce que c'est ainsi que Dawn structure son panier. Dawn divise la page du panier en deux sections : main-cart-items.liquid (le tableau des articles) et main-cart-footer.liquid (totaux, bouton de paiement, attributs). Horizon ne réplique pas cette division.

Horizon est le fleuron d'une nouvelle génération de thèmes Shopify construits sur le framework Horizon. Le principe architectural est : chaque élément interactif significatif de la page est un composant web autonome. Le tiroir du panier, le sélecteur de variante, la recherche prédictive, aucun d'eux n'est une section Liquid monolithique comme le fait Dawn. Ce sont plutôt des éléments personnalisés encapsulés composés ensemble à l'intérieur d'un seul fichier de section main-cart.liquid.

Cela a créé une confusion immédiate au lancement de Horizon lors de Summer Editions 2025. En février 2026, les forums communautaires Shopify étaient remplis de marchands sur Horizon 3.3.0 cherchant main-cart-items.liquid dans leur répertoire sections/ et ne trouvant rien, car le fichier n'y a jamais été.

À quoi ressemble réellement l'architecture du panier Horizon

Au lieu d'un fichier de section séparé par zone du panier, la page du panier de Horizon est structurée autour de main-cart.liquid comme section externe, avec l'élément personnalisé <cart-items-component> gérant le rendu interactif des articles à l'intérieur.

Les décisions architecturales clés, directement depuis le dépôt GitHub officiel de Horizon :

• Rendu côté serveur en premier. Le HTML est rendu par les serveurs de Shopify via Liquid. La logique métier comme le formatage des devises et les traductions reste sur le serveur, pas sur le client.
• Amélioration progressive web native. Le thème cible les navigateurs modernes sans polyfills, et le re-rendu asynchrone de l'état du panier (mises à jour de quantité, suppressions) est géré avec parcimonie comme amélioration progressive au-dessus du HTML rendu côté serveur.
• JavaScript scopé. Horizon inclut une classe JS spécifique qui mesure les performances pour les composants comme le formulaire de produit, le tiroir du panier et la remise du panier, maintenant le poids de JS minimal par composant.

Le cart-items-component est l'élément personnalisé (<cart-items-component>) qui enveloppe le tableau des articles. Il écoute les événements de changement du panier (ajout, suppression, mise à jour de quantité) et re-rend son HTML interne via l'API Cart Ajax sans rechargement complet de la page. Son modèle Liquid se trouve à l'intérieur de main-cart.liquid, pas dans un fichier séparé.

Les attributs du panier (champs personnalisés au niveau de la commande comme un message cadeau ou un sélecteur de date) sont capturés via main-cart-footer.liquid. Selon la documentation du modèle panier de Shopify, vous ajoutez un <input> avec name="attributes[votre-nom-de-champ]" et form="cart" à l'intérieur de ce fichier de pied de page. Cet attribut est ensuite accessible via {{ cart.attributes['votre-nom-de-champ'] }}.

Les propriétés des articles de ligne (données personnalisées par produit) ne sont pas rendues automatiquement par cart-items-component. Vous devez boucler cart.items à l'intérieur de main-cart.liquid et afficher le hash .properties de chaque article. La propre documentation de Shopify note que si deux du même article sont ajoutés avec des propriétés d'article de ligne uniques, ils se divisent en articles de ligne séparés, un comportement à prendre en compte dans votre logique de modèle.

Comment personnaliser le panier de manière sécurisée sur Horizon

Horizon publie des mises à jour de thème hebdomadaires. Si vous éditez les fichiers principaux directement, ces modifications seront écrasées lors de la prochaine mise à jour. Le dépôt GitHub a même signalé une divergence de version en direct : en avril 2026, le Theme Store était à la v3.5.1 tandis que le dépôt GitHub était épinglé à la v3.4.0, ce qui signifie que certains changements arrivaient d'abord en magasin. Cela renforce le besoin d'un flux Git approprié.

La configuration GitHub à trois branches

Le guide officiel de Shopify Growth Services (publié en novembre 2025) recommande de gérer toutes les personnalisations de Horizon via une stratégie de branchement disciplinée :

1. upstream/horizon, suit directement le dépôt officiel Shopify/horizon. Vous tirez d'abord les mises à jour ici.
2. main, votre branche personnalisée et prête pour la production. Vous fusionnez upstream dans main après avoir examiné les différences.
3. Branches de fonctionnalités, toutes les nouvelles personnalisations du panier sont construites ici et validées par PR dans main.

Pour configurer upstream, accédez à votre dossier de thème local et exécutez :

git remote add upstream https://github.com/Shopify/horizon.git
git fetch upstream

Quand Shopify publie une nouvelle version de Horizon, tirez-la dans votre branche upstream, résolvez les conflits sur vos fichiers personnalisés, et fusionnez. Cela gardera vos personnalisations du panier intactes à travers chaque mise à jour hebdomadaire.

Où placer réellement vos personnalisations du panier

Évitez la tentation de copier la version complète de main-cart.liquid dans une version préfixée custom. sauf si c'est absolument nécessaire. Une copie complète signifie que vous devez comparer manuellement et réappliquer chaque future mise à jour de Shopify à cette section. À la place, ajoutez uniquement ce dont vous avez besoin dans les nouveaux fichiers de blocs si possible, et gardez la section principale intacte.

Construire des extensions de panier interactives en tant que composants web

La philosophie de performance de Horizon est explicite : pas de bibliothèque de carrousel ou d'interface utilisateur externe. Si vous avez besoin d'un comportement interactif à l'intérieur du panier (un curseur de quantité animé, une barre de progression d'expédition gratuite en temps réel), construisez-le en tant que Web Component vanilla qui s'initialise uniquement quand visible. Utilisez IntersectionObserver pour différer l'initialisation de tout ce qui n'est pas immédiatement dans la fenêtre d'affichage, et écrivez vos styles à l'intérieur de balises {% style %} pour les garder scopés et libres de requêtes HTTP supplémentaires.

class CartUpsellBadge extends HTMLElement {
  connectedCallback() {
    // Initialise seulement quand le panier est ouvert / l'élément est visible
    this._observer = new IntersectionObserver((entries) => {
      if (entries[0].isIntersecting) {
        this._init();
        this._observer.disconnect();
      }
    });
    this._observer.observe(this);
  }

  _init() {
    // Récupère les données upsell, rend dans this.innerHTML
  }
}
customElements.define('cart-upsell-badge', CartUpsellBadge);

Chargez ce script via <script type="module"> pour que le navigateur le gère efficacement, correspondant au propre pattern de chargement de script de Horizon.

Le problème de compatibilité des applications Shadow DOM

C'est le problème qui attrape la plupart des marchands au milieu du projet. Les applications construites pour l'ancienne architecture Online Store 2.0 de Dawn se branchent souvent sur le panier en interrogeant le DOM pour une entrée de quantité ou une plage de total du panier et en écoutant les événements de changement. Ce pattern casse sur Horizon.

Parce que les composants du panier de Horizon sont des composants web, les applications utilisant l'encapsulation Shadow DOM bloquent l'ancien pattern document.querySelector('.cart-item__quantity'). Les éléments internes de l'élément personnalisé ne sont pas accessibles de l'extérieur de la racine shadow via des requêtes DOM standard.

Avant d'installer une application de panier sur Horizon, vérifiez explicitement dans la liste de l'application une note "Support Horizon". Les applications qui ont reçu un badge "Built for Shopify" ont été testées en performance, mais le statut du badge seul ne garantit pas la compatibilité Shadow DOM. En cas de doute, installez sur un thème en double et testez les mises à jour de quantité, les suppressions et le flux de paiement de bout en bout avant de lancer en production.

Le décalage GitHub actuel et ce qu'il signifie pour vous

Depuis le milieu 2026, le dépôt GitHub de Shopify/horizon a eu des périodes où il a pris du retard par rapport à la version en direct dans le Theme Store. En avril 2026, les développeurs communautaires ont noté que le dépôt était à la v3.4.0 tandis que le Theme Store servait la v3.5.1. Shopify a confirmé que la branche principale peut inclure du code pour les fonctionnalités pas encore publiées, ce qui signifie que le thème publié et le dépôt peuvent être désynchronisés dans les deux sens.

Implication pratique : ne traitez pas le dépôt GitHub comme la source canonique de la version s'exécutant dans votre magasin. Tirez le dernier thème depuis votre admin Shopify (Online Store > Thèmes > Télécharger le fichier de thème) et comparez-le avec le dépôt GitHub avant de faire des suppositions sur le code en direct. Utilisez Theme Check (fourni avec Shopify CLI et disponible comme extension VS Code que Horizon recommande automatiquement) pour valider votre Liquid avant chaque déploiement.

Une note sur le bug du navigateur dans l'application Instagram (juin 2026)

Un problème en direct à connaître : à partir de la semaine du 14 juin 2026, plusieurs marchands Horizon ont signalé que la navigation supplémentaire après le chargement initial de la page à l'intérieur des navigateurs intégrés d'Instagram, Facebook et TikTok produit un écran blanc vierge. L'équipe des thèmes de Shopify a reconnu le problème le 17 juin 2026, confirmé qu'une solution de contournement existe, et déclaré que la cause racine peut être liée au comportement du navigateur intégré plutôt qu'au thème lui-même. Si vous exécutez des campagnes de commerce social qui dirigent le trafic via ces navigateurs intégrés, contactez le support Shopify pour la solution de contournement actuelle pendant que le correctif complet est en cours.

Résumé : le modèle mental correct pour le panier de Horizon

Arrêtez de chercher main-cart-items.liquid. C'est un concept de Dawn. Le panier de Horizon est :

• Une section externe : main-cart.liquid
• Un composant web interactif : <cart-items-component> gérant les re-rendus Ajax
• Une section de pied de page : main-cart-footer.liquid pour les attributs du panier et le formulaire de paiement
• Répertoire de blocs : où vivent toutes vos additions personnalisées

Travaillez dans ce modèle, gérez vos changements via une branche upstream GitHub appropriée, et vous pouvez personnaliser en toute sécurité le panier de Horizon sans redouter chaque mise à jour hebdomadaire.

Si vous avez besoin d'aide pratique pour construire une expérience de panier personnalisée sur Horizon, consultez ce que nous faisons en tant que développeur de thème Shopify ou vérifiez notre service d'optimisation de la vitesse de Shopify si la performance du panier est la préoccupation sous-jacente.