Warum Horizon keine main-cart-items.liquid hat (und wie Sie die cart-items-component stattdessen anpassen)

Horizon hat keine Sectionsdatei main-cart-items.liquid. Diese Datei existiert in Dawn, nicht in Horizon. In Horizon wird das Rendern von Warenkorbausgaben durch main-cart.liquid (die Section) zusammen mit dem benutzerdefinierten Web-Element cart-items-component verwaltet. Das Anpassen des Warenkorbs bedeutet, innerhalb dieser Web-Component-Architektur zu arbeiten, anstatt eine einfache Liquid-Section zu bearbeiten.

Wichtigste Erkenntnisse

• Horizon ersetzte das monolithische Muster main-cart-items.liquid durch eine in sich geschlossene cart-items-component Web Component.
• Das direkte Bearbeiten von Horizon-Kerndateien wird beim nächsten Theme-Update überschrieben (Horizon veröffentlicht wöchentliche Releases).
• Warenkorbattribute gehören in main-cart-footer.liquid; Zeileneigenschaftswerte werden durch cart.items Iteration in main-cart.liquid gerendert.
• Der sichere Anpassungspfad ist: neue Block-Dateien in blocks/, prefixierte Section-Dateien und ein GitHub-Upstream-Branch zum sauberen Abrufen von Shopify-Updates.
• Apps, die für die ältere Online Store 2.0 Architektur entwickelt wurden, brechen oft auf Horizons Warenkorb, da Web Components innerhalb von Shadow DOM ausgeführt werden.

Warum die gesuchte Datei nicht existiert

Shopifys Hilfedokumente und unzählige Tutorials verweisen auf main-cart-items.liquid, weil Dawn seinen Warenkorb so strukturiert. Dawn teilt die Warenkorbseite in zwei Sections auf: main-cart-items.liquid (die Zeilentabelle) und main-cart-footer.liquid (Summen, Checkout-Button, Attribute). Horizon repliziert diese Aufteilung nicht.

Horizon ist das Flaggschiff einer neuen Generation von Shopify-Themes, die auf dem Horizon-Framework aufgebaut sind. Das Architekturgrundsatz ist: Jedes bedeutungsvolle interaktive Teil der Seite ist ein in sich geschlossenes Web Component. Der Warenkorbbereich, der Variantenwähler, die vorausschauende Suche, keiner von ihnen ist eine monolithische Liquid-Section wie in Dawn. Stattdessen sind sie gekapselte benutzerdefinierte Elemente, die zusammen in einer einzigen main-cart.liquid Section-Datei komponiert werden.

Dies führte zu sofortiger Verwirrung, als Horizon auf Summer Editions 2025 gestartet wurde. Bis Februar 2026 waren die Shopify Community-Foren voll von Händlern auf Horizon 3.3.0, die ihr sections/ Verzeichnis nach main-cart-items.liquid durchsuchten und nichts fanden, weil sie nie dort war.

Wie die Horizon Warenkorb-Architektur wirklich aussieht

Anstelle einer separaten Section-Datei pro Warenkorbzone ist die Warenkorbseite von Horizon um main-cart.liquid als äußere Section strukturiert, wobei das benutzerdefinierte Element <cart-items-component> das interaktive Rendern von Zeilenausgaben darin verwaltet.

Die wichtigsten Architekturbescheidungen, direkt aus dem offiziellen Horizon GitHub Repo:

• Server-gerenderter First. HTML wird von Shopifys Servern über Liquid gerendert. Geschäftslogik wie Währungsformatierung und Übersetzungen bleibt auf dem Server, nicht auf dem Client.
• Web-native progressive Verbesserung. Das Theme zielt auf moderne Browser ohne Polyfills ab, und das asynchrone Neurendern von Warenkorbstatus (Mengenupdates, Löschungen) wird sparsam als progressive Verbesserung über dem server-gerendertem HTML verwaltet.
• Scoped JavaScript. Horizon enthält eine bestimmte JS-Klasse, die die Leistung für Komponenten wie das Produktformular, den Warenkorbbereich und Warenkorbrabatte misst und das JS-Gewicht pro Komponente minimal hält.

Das cart-items-component ist das benutzerdefinierte Element (<cart-items-component>), das die Zeilentabelle umhüllt. Es lauscht auf Warenkorbänderungsereignisse (Hinzufügen, Entfernen, Mengenupdate) und rendert sein inneres HTML über die Cart Ajax API neu, ohne eine vollständige Seitenneuladung. Seine Liquid-Vorlage lebt innerhalb von main-cart.liquid, nicht in einer separaten Datei.

Warenkorbattribute (Order-Level-Benutzerdefinierte Felder wie eine Geschenkmitteilung oder ein Datumswähler) werden über main-cart-footer.liquid erfasst. Gemäß Shopifys Dokumentation zu Warenkorbvorlagen fügen Sie ein <input> mit name="attributes[your-field-name]" und form="cart" innerhalb dieser Footer-Datei hinzu. Dieses Attribut ist dann über {{ cart.attributes['your-field-name'] }} zugänglich.

Zeileneigenschaften (pro-Produkt benutzerdefinierte Daten) werden von cart-items-component nicht automatisch gerendert. Sie müssen cart.items innerhalb von main-cart.liquid durchlaufen und die .properties Hash jedes Artikels ausgeben. Shopifys eigene Docs vermerken, dass, wenn zwei desselben Artikels mit eindeutigen Zeileneigenschaften hinzugefügt werden, sie sich in separate Zeilenausgaben aufteilen, ein Verhalten, das in Ihrer Logik zu berücksichtigen wert ist.

Wie Sie den Warenkorb sicher auf Horizon anpassen

Horizon veröffentlicht wöchentliche Theme-Updates. Wenn Sie Kerndateien direkt bearbeiten, werden diese Änderungen beim nächsten Update überschrieben. Das GitHub Repo hat sogar eine Live-Versionsdiskrepanz kennzeichnet: Ab April 2026 war der Theme Store bei v3.5.1, während das GitHub Repo bei v3.4.0 fixiert war, was bedeutet, dass einige Änderungen zuerst im Store landeten. Dies unterstreicht die Notwendigkeit eines ordnungsgemäßen Git-Workflows.

Das drei-Branch GitHub Setup

Shopifys offizieller Growth Services Guide (veröffentlicht November 2025) empfiehlt, alle Horizon-Anpassungen durch eine disziplinierte Branch-Strategie zu verwalten:

1. upstream/horizon, verfolgt das offizielle Shopify/horizon Repository direkt. Sie pullen Updates hier zuerst.
2. main, Ihr angepasster, produktionsbereiter Branch. Sie mergen Upstream in Main nach Review von Unterschieden.
3. Feature Branches, alle neuen Warenkorbkustomierungen werden hier erstellt und in main PR'd.

Navigieren Sie zu Ihrem lokalen Theme-Ordner und führen Sie aus:

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

Wenn Shopify eine neue Horizon-Version veröffentlicht, pullen Sie sie in Ihren Upstream-Branch, beheben Sie Konflikte in Ihren benutzerdefinierten Dateien und mergen. Dies hält Ihre Warenkorbkustomierungen über jedes wöchentliche Update hinweg intakt.

Wo Sie Ihre Warenkorbkustomierungen tatsächlich einfügen

Widerstehen Sie der Versuchung, die vollständige main-cart.liquid in eine custom. prefixierte Version zu kopieren, es sei denn, Sie müssen es unbedingt tun. Eine vollständige Kopie bedeutet, dass Sie jeden zukünftigen Shopify-Update manuell unterscheiden und erneut anwenden müssen. Fügen Sie stattdessen nur das hinzu, was Sie brauchen, in neuen Block-Dateien, wo möglich, und halten Sie die Kern-Section unberührt.

Interaktive Warenkorbverlängerungen als Web Components erstellen

Horizons Leistungsphilosophie ist eindeutig: keine externen Carousel- oder UI-Bibliotheken. Wenn Sie interaktives Verhalten im Warenkorb benötigen (ein animierter Mengenschrittstepper, eine Echtzeit-Versandgratisleisten-Fortschrittsanzeige), erstellen Sie es als reines Web Component, das nur bei Sichtbarkeit initialisiert wird. Verwenden Sie IntersectionObserver, um die Initialisierung von allem, das nicht sofort im Viewport ist, zu verschieben, und schreiben Sie Ihre Styles innerhalb von {% style %} Tags, um sie gescoped und kostenfrei für zusätzliche HTTP-Anfragen zu halten.

class CartUpsellBadge extends HTMLElement {
  connectedCallback() {
    // Initialisieren Sie nur, wenn Warenkorb offen ist / Element sichtbar ist
    this._observer = new IntersectionObserver((entries) => {
      if (entries[0].isIntersecting) {
        this._init();
        this._observer.disconnect();
      }
    });
    this._observer.observe(this);
  }

  _init() {
    // Abrufen von Upsell-Daten, Rendern in this.innerHTML
  }
}
customElements.define('cart-upsell-badge', CartUpsellBadge);

Laden Sie dieses Skript über <script type="module">, damit der Browser es effizient handhabt und Horizons eigenes Skriptlademuster abgleicht.

Das Shadow DOM App-Kompatibilitätsproblem

Das ist das Gotcha, das die meisten Händler mitten im Projekt erwischt. Apps, die für Dawns ältere Online Store 2.0 Architektur entwickelt wurden, hängen oft mit einem Hook in den Warenkorb ab, indem sie das DOM nach einem Mengeneingabe- oder Warenkorbsummenelement abfragen und auf Änderungsereignisse lauschen. Dieses Muster funktioniert auf Horizon nicht.

Weil Horizons Warenkorbkomponenten Web Components sind, blockieren Apps, die das alte Muster document.querySelector('.cart-item__quantity') verwenden, mit Shadow DOM Kapselung. Die Interna des benutzerdefinierten Elements sind nicht von außerhalb des Shadow Root über Standard-DOM-Abfragen zugänglich.

Bevor Sie eine Warenkorbapp auf Horizon installieren, überprüfen Sie die App-Auflistung ausdrücklich auf eine "Horizon Support" Notiz. Apps, die ein "Built for Shopify" Abzeichen erhalten haben, wurden leistungsgetestet, aber der Abzeichenstatus allein garantiert keine Shadow DOM Kompatibilität. Im Zweifelsfall installieren Sie auf einem doppelten Theme und testen Sie Mengenaktualisierungen, Löschungen und den Checkout-Flow end-to-end, bevor Sie live gehen.

Das aktuelle GitHub Lag und was es für Sie bedeutet

Ab Mitte 2026 hat das Shopify/horizon GitHub Repo Perioden gehabt, in denen es hinter der im Theme Store live Version zurückblieb. Im April 2026 verzeichneten Community-Entwickler, dass das Repo bei v3.4.0 war, während der Theme Store v3.5.1 diente. Shopify bestätigte, dass der Main-Branch Code für noch nicht veröffentlichte Funktionen enthalten kann, was bedeutet, dass das veröffentlichte Theme und das Repo in beide Richtungen desynchronisiert sein können.

Praktische Implikation: Behandeln Sie das GitHub Repo nicht als kanonische Quelle der Version, die in Ihrem Store ausgeführt wird. Pullen Sie das neueste Theme aus Ihrem Shopify Admin (Online Store > Themes > Theme-Datei herunterladen) und unterscheiden Sie es gegen das GitHub Repo, bevor Sie Annahmen treffen, welcher Code live ist. Verwenden Sie Theme Check (im Shopify CLI gebündelt und als VS Code Extension verfügbar, die Horizon automatisch empfiehlt), um Ihre Liquid vor jedem Deployment zu validieren.

Ein Hinweis auf das Instagram In-App-Browser Bug (Juni 2026)

Ein Live-Problem, das es wert ist zu kennen: ab der Woche des 14. Juni 2026 berichteten mehrere Horizon-Händler, dass weitere Navigation nach dem anfänglichen Seitenladevorgang in den In-App-Browsern von Instagram, Facebook und TikTok einen leeren weißen Bildschirm erzeugt. Shopifys Theme-Team bestätigte das Problem am 17. Juni 2026, bestätigte, dass eine Lösung existiert, und sagte, dass die Grundursache mit In-App-Browser-Verhalten zusammenhängen kann, anstatt mit dem Theme selbst. Wenn Sie Social Commerce Kampagnen führen, die Traffic durch diese In-App-Browser fahren, kontaktieren Sie Shopify Support für die aktuelle Umgehung, während der vollständige Fix läuft.

Zusammenfassung: Das richtige mentale Modell für Horizons Warenkorb

Hören Sie auf, nach main-cart-items.liquid zu suchen. Das ist ein Dawn-Konzept. Horizons Warenkorb ist:

• Eine äußere Section: main-cart.liquid
• Ein interaktives Web Component: <cart-items-component> verwaltet Ajax-Neurender
• Eine Footer-Section: main-cart-footer.liquid für Warenkorbattribute und das Checkout-Formular
• Blocks Verzeichnis: wo alle Ihre benutzerdefinierten Ergänzungen leben

Arbeiten Sie innerhalb dieses Modells, verwalten Sie Ihre Änderungen durch einen ordnungsgemäßen GitHub Upstream-Branch, und Sie können Horizons Warenkorb sicher anpassen, ohne sich vor jedem wöchentlichen Update zu fürchten.

Wenn Sie praktische Hilfe beim Aufbau einer benutzerdefinierten Warenkorboberfläche auf Horizon benötigen, sehen Sie, was wir als Shopify Theme Developer tun oder überprüfen Sie unseren Shopify Speed Optimization Service, wenn Warenkorbleistung die zugrunde liegende Bedenken ist.