Luma-UI-Components durch Hyvä-Templates ablösen

1. Warum Hyvä die UI-Component-Schicht entfernt

Luma rendert weite Teile der Storefront über UI-Components: eine Kombination aus jsLayout-XML, RequireJS-Modulen und Knockout.js-Templates, die im Browser nach dem eigentlichen Seitenaufbau einen zweiten, clientseitigen Render-Durchlauf ausführen. Jede zusätzliche UI-Component bedeutet ein weiteres JS-Modul, das per RequireJS aufgelöst, geladen und initialisiert werden muss, bevor der sichtbare Inhalt tatsächlich interaktiv wird. Genau diese Schicht entfernt Hyvä für die Storefront vollständig: Statt eine leere Hülle zu rendern und sie anschließend per Knockout zu befüllen, liefert Hyvä fertig serverseitig gerenderte phtml-Templates aus und ergänzt Interaktivität gezielt nur dort, wo sie wirklich gebraucht wird - mit Alpine.js.

Der Effekt ist messbar: Ohne Knockout.js, ohne RequireJS-Dependency-Graph und ohne UI-Components-Runtime sinkt die JS-Bundle-Größe auf der Storefront drastisch, die Time-to-Interactive verbessert sich, weil kein zweiter Render-Pass mehr nötig ist, und Lighthouse-Werte steigen ohne zusätzliche Optimierungsarbeit. Ein Hyvä-Template mit Alpine.js-Direktiven ist beim ersten Byte bereits vollständig lesbar; Alpine hydriert lediglich die interaktiven Teile, statt die gesamte Komponente aus einem JSON-Datenmodell neu aufzubauen.

Für Agenturen, die einen Shop von Luma auf Hyvä migrieren, bedeutet das: Jede vorhandene UI-Component muss identifiziert, verstanden und durch ein gleichwertiges Hyvä-Template ersetzt werden - nicht nur optisch, sondern auch in der zugrunde liegenden Datenlogik. Wer diesen Schritt überspringt und Knockout-Fragmente unverändert in ein Hyvä-Theme einbaut, handelt sich zwei parallele JS-Frameworks, doppelte Ladezeiten und schwer nachvollziehbare Bugs ein.

2. jsLayout-XML und ko-Templates lesen, bevor man migriert

Bevor eine einzige Zeile Alpine-Code geschrieben wird, muss die bestehende UI-Component verstanden werden - nicht nur ihr Markup, sondern die tatsächliche Datenlogik dahinter. Der Ausgangspunkt ist immer die jsLayout-XML im Layout-Handle: Sie definiert, welche Knockout-Komponente (component) geladen wird, welches Template (config/template) sie rendert und welche Konfigurationswerte sie vom Server mitbekommt. Erst wenn klar ist, welche Daten die Komponente tatsächlich konsumiert, lässt sich entscheiden, wie diese Daten in einem Hyvä-Template ohne Knockout bereitgestellt werden.

Im zweiten Schritt folgt man dem component-Pfad zur eigentlichen JS-View-Model-Datei und prüft, welche Knockout-Observables sie exponiert und welche data-bind-Ausdrücke das zugehörige ko-Template verwendet. Die vier häufigsten Bindings - visible, text, foreach und click - decken in der Praxis die überwiegende Mehrheit aller Luma-UI-Components ab und lassen sich, wie im folgenden Beispiel eines Compare-Widgets, direkt einem Alpine-Äquivalent zuordnen.

<!-- OLD: catalog_product_compare_index.xml (Luma layout, jsLayout XML) -->
<referenceContainer name="content">
    <block class="Magento\Catalog\Block\Product\Compare\Sidebar" name="catalog.compare.sidebar"
           template="Magento_Catalog::product/compare/sidebar.phtml">
        <arguments>
            <argument name="jsLayout" xsi:type="array">
                <item name="components" xsi:type="array">
                    <item name="compareWidget" xsi:type="array">
                        <item name="component" xsi:type="string">Magento_Catalog/js/compare-products</item>
                        <item name="config" xsi:type="array">
                            <item name="template" xsi:type="string">Magento_Catalog/compare/widget</item>
                            <item name="countUrl" xsi:type="string">catalog/product_compare/countPost</item>
                        </item>
                    </item>
                </item>
            </argument>
        </arguments>
    </block>
</referenceContainer>

<!-- OLD: Magento_Catalog/web/template/compare/widget.html (Knockout ko-template) -->
<div class="compare-widget" data-bind="visible: count() > 0">
    <a class="action compare" data-bind="click: openCompareList, attr: { title: $t('Compare Products') }">
        <span data-bind="text: $t('Compare Products')"></span>
        <span class="counter qty" data-bind="text: count"></span>
    </a>
</div>

3. Von Knockout-Bindings zu Alpine-Direktiven

Die Übersetzung von Knockout nach Alpine folgt einem festen Muster: data-bind="visible: ..." wird zu x-show="...", data-bind="text: ..." wird zu x-text="...", data-bind="foreach: ..." wird zu einem <template x-for="...">-Block, und data-bind="click: ..." wird zu x-on:click="...". Der eigentliche Unterschied liegt aber nicht in der Syntax, sondern im Reaktivitätsmodell: Knockout-Observables sind explizite JS-Objekte mit Subscriptions, die man manuell erzeugen und pflegen muss, während Alpine seine Reaktivität über ein Proxy-Objekt bereitstellt, das direkt aus einem einfachen JavaScript-Objekt in x-data entsteht - ohne zusätzliche Wrapper-Funktionen wie ko.observable().

Das folgende Beispiel zeigt das Compare-Widget aus Abschnitt 2 als vollständiges Hyvä-Template-Äquivalent: Die Zähler-Logik, die zuvor über einen Knockout-Provider und einen AJAX-Request nachgeladen wurde, kommt hier direkt aus dem serverseitig gerenderten HTML, und Alpine übernimmt nur noch die Anzeige-Logik.

// NEW: Magento_Catalog/web/js/compare-widget.js (registered as Alpine.data)
document.addEventListener('alpine:init', () => {
    Alpine.data('compareWidget', () => ({
        count: 0,
        compareUrl: '',
        init() {
            // Data comes from a PHP ViewModel, rendered once into the DOM - no client round trip
            this.count = parseInt(this.$el.dataset.initialCount, 10) || 0;
            this.compareUrl = this.$el.dataset.compareUrl;
        },
        openCompareList() {
            window.location.href = this.compareUrl;
        }
    }));
});

/* Usage inside compare-widget.phtml (markup replaces the old ko-template):
<div x-data="compareWidget"
     data-initial-count="<?= (int) $viewModel->getCompareCount() ?>"
     data-compare-url="<?= $escaper->escapeUrl($block->getCompareUrl()) ?>"
     x-show="count > 0">
    <a class="action compare" x-on:click="openCompareList">
        <span>Compare Products</span>
        <span class="counter qty" x-text="count"></span>
    </a>
</div>
*/

Feinere Knockout-Konstrukte übersetzen sich ebenso konsequent: Ein ko.computed() wird zu einer Getter-Methode innerhalb von x-data, ein subscribe()-Callback wird zu Alpines $watch(), und ein foreach mit Zugriff auf $index wird zu einem <template x-for> mit :key-Bindung. Wer diese Entsprechungen einmal sauber notiert hat, kann sie als Checkliste für jede weitere UI-Component-Migration wiederverwenden, statt jedes Widget von Grund auf neu zu analysieren.

4. Praxisbeispiel: Toolbar-Sorter migrieren

Der Produktlisten-Toolbar-Sorter ist eine der am häufigsten migrierten UI-Components, weil er auf praktisch jeder Kategorieseite sichtbar ist. In Luma verwaltet ein Knockout-View-Model die aktuelle Sortierreihenfolge, die Sortierrichtung und den aktiven Ansichtsmodus (Grid oder Liste) und rendert daraus ein select-Element sowie eine Liste von Modus-Buttons über foreach.

Das folgende ko-Template zeigt die Ausgangslage: visible blendet den gesamten Sorter aus, wenn keine Ergebnisse vorliegen, text rendert die Labels, foreach iteriert über die verfügbaren Modi, und click löst Sortier- und Modus-Wechsel aus.

<!-- OLD: Magento_Catalog/web/template/product/list/toolbar.html (Knockout) -->
<div class="toolbar-sorter sorter" data-bind="visible: hasCollectionData()">
    <label class="sorter-label" data-bind="text: $t('Sort By')" for="sorter"></label>
    <select id="sorter" class="sorter-options"
            data-bind="options: options, optionsText: 'label', value: currentOrder, event: { change: apply }"></select>
    <div class="sorter-action" data-bind="css: directionClass, click: setDirection, attr: { title: $t('Set Descending Direction') }">
        <span data-bind="text: $t('Set Descending Direction')"></span>
    </div>
</div>
<div class="modes" data-bind="foreach: modes">
    <a class="modes-mode" data-bind="attr: { title: label }, click: $parent.setModeAndReload, css: { 'active': $parent.isModeActive($data) }">
        <span data-bind="text: label"></span>
    </a>
</div>

Die Migration ersetzt den kompletten Knockout-View-Model-Layer durch eine einzige Alpine.data()-Komponente, deren Startzustand (Sortieroptionen, aktuelle Sortierung) direkt aus der PHP-Ebene als JSON in das Markup geschrieben wird. Kein AJAX-Request lädt die Optionen nach, kein RequireJS-Modul muss aufgelöst werden - das Hyvä-Template ist beim ersten Rendern bereits vollständig.

<!-- NEW: Magento_Catalog/product/list/toolbar.phtml (Hyvä-Template + Alpine.js) -->
<div x-data="toolbarSorter(<?= /* @noEscape */ $viewModel->getSortOptionsJson() ?>, '<?= $escaper->escapeJs($viewModel->getCurrentOrder()) ?>')">
    <div class="toolbar-sorter sorter" x-show="hasResults">
        <label class="sorter-label" for="sorter">Sort By</label>
        <select id="sorter" class="sorter-options" x-model="currentOrder" x-on:change="apply">
            <template x-for="option in options" :key="option.value">
                <option :value="option.value" x-text="option.label"></option>
            </template>
        </select>
        <button type="button" class="sorter-action" :class="directionClass" x-on:click="setDirection" title="Set Descending Direction"></button>
    </div>
    <div class="modes">
        <template x-for="mode in modes" :key="mode.value">
            <a class="modes-mode" :class="{ active: isModeActive(mode) }" :title="mode.label" x-on:click="setModeAndReload(mode)" x-text="mode.label"></a>
        </template>
    </div>
</div>

<!-- Alpine.data() registration, loaded as a separate JS asset and CSP-registered via $hyvaCsp->registerInlineScript() -->
document.addEventListener('alpine:init', () => {
    Alpine.data('toolbarSorter', (options, initialOrder) => ({
        options,
        currentOrder: initialOrder,
        hasResults: options.length > 0,
        modes: [{ value: 'grid', label: 'Grid' }, { value: 'list', label: 'List' }],
        directionClass: 'sort-asc',
        apply() {
            window.location.search = `?product_list_order=${this.currentOrder}`;
        },
        setDirection() {
            this.directionClass = this.directionClass === 'sort-asc' ? 'sort-desc' : 'sort-asc';
            window.location.search = `?product_list_dir=${this.directionClass}`;
        },
        isModeActive(mode) {
            return mode.value === (new URLSearchParams(window.location.search)).get('product_list_mode');
        },
        setModeAndReload(mode) {
            window.location.search = `?product_list_mode=${mode.value}`;
        }
    }));
});

5. Zweites Beispiel: Swatch-Renderer mit Alpine.data()

Der Swatch-Renderer ist eines der komplexeren Beispiele für eine Luma-UI-Component, weil er in der Praxis ein Hybrid ist: ein jQuery-Widget, das intern ein Knockout-View-Model kapselt und über Events mit Media-Gallery und Preisbox synchronisiert. Diese doppelte Abstraktion - jQuery-Widget-Registrierung plus Knockout-Observable-Kette - ist genau die Art von Komplexität, die bei der Migration zu einem Hyvä-Template verschwindet, weil ein einziges Alpine.data()-Objekt beide Schichten ersetzt.

Der Auswahlzustand jedes Attributs wird in einem einfachen Objekt gehalten, die Vollständigkeitsprüfung erfolgt über eine berechnete Eigenschaft, und statt eines internen Knockout-subscribe()-Callbacks löst die Komponente ein natives Custom Event aus, auf das Gallery und Preisbox unabhängig voneinander lauschen können.

// NEW: Magento_Swatches/web/js/swatch-renderer.js (Alpine.data(), no jQuery widget wrapper)
document.addEventListener('alpine:init', () => {
    Alpine.data('swatchRenderer', (attributes, initialSelection = {}) => ({
        attributes,
        selected: { ...initialSelection },
        get isComplete() {
            return this.attributes.every((attribute) => this.selected[attribute.id] !== undefined);
        },
        selectSwatch(attributeId, optionId) {
            this.selected = { ...this.selected, [attributeId]: optionId };
            // Replaces the old ko subscribe() chain that synced gallery and price box
            this.$dispatch('swatch-selection-changed', { selected: this.selected, complete: this.isComplete });
        },
        isSelected(attributeId, optionId) {
            return this.selected[attributeId] === optionId;
        }
    }));
});

Die Gallery- und Preisbox-Komponenten hören auf dieses swatch-selection-changed-Event mit x-on:swatch-selection-changed.window und aktualisieren sich unabhängig - genau die lose Kopplung, die vorher über einen zentralen Knockout-Provider laufen musste. Ein weiterer Vorteil: Da keine RequireJS-Modul-Registrierung mehr nötig ist, lässt sich die Komponente ohne Build-Schritt direkt im Browser debuggen.

6. ViewModel statt UI-Component-Provider

In Luma bekommen UI-Components ihre Daten typischerweise über einen "Provider", der aus der Magento_Ui/js/lib/registry aufgelöst wird und entweder mit einer separaten AJAX-Anfrage an einen UI-Component-Data-Provider-Endpunkt Daten nachlädt oder über einen JS-Mixin zusätzliche Felder zur Laufzeit injiziert. Diese ganze Indirektionskette - Provider, Registry, Data-Provider-Endpunkt, Mixin - entfällt bei einem Hyvä-Template vollständig. Die gleichen Daten werden einmalig serverseitig in einer ViewModel-Klasse (ArgumentInterface) aufbereitet, per Layout-XML in den Block injiziert und direkt im phtml-Template als JSON oder als PHP-Werte ausgegeben.

Ein typisches Muster dafür ist <?= /* @noEscape */ $viewModel->getSwatchDataJson() ?> als Startwert für x-data - keine dataScope-Bindung, kein separates .json-Endpoint, keine Registry-Auflösung zur Laufzeit. Dieses Vorgehen ersetzt eine ganze Architekturschicht durch eine einzige, testbare PHP-Klasse.

Der Testbarkeits-Gewinn ist real: Eine ViewModel-Klasse lässt sich mit PHPUnit ohne Browser oder JS-Runtime testen, während ein Knockout-View-Model für dieselbe Anzeigelogik einen JS-Testlauf mit Mock-DOM benötigt hätte. Für einfache Anzeigelogik - Sortieroptionen, Swatch-Daten, Vergleichszähler - ist der PHP-Weg in Entwicklung, Review und Wartung durchgängig günstiger als das Knockout-Äquivalent.

7. Drittanbieter-Module mit Luma-UI-Components

Die Realität in gewachsenen Shops: Viele Drittanbieter-Erweiterungen - Checkout-Add-ons, Produktkonfiguratoren, Bonusprogramm-Widgets - liefern weiterhin klassische Luma-UI-Components aus und setzen voraus, dass Knockout.js und RequireJS auf der Storefront verfügbar sind. Hyvä entfernt diese Bibliotheken nicht zwangsläufig aus dem gesamten Magento-Stack, sondern konzentriert sich auf die eigene Theme-Ebene; für Fremdmodule, die noch nicht auf Hyvä-Templates umgestellt haben, braucht es eine bewusste Kompatibilitätsstrategie.

Die gängigste Strategie ist eine gezielte Layout-XML-Anpassung: Der Block, der die Knockout-UI-Component referenziert, wird per remove oder Reihenfolge-Override deaktiviert und durch ein eigenes phtml-Template mit gleicher Funktionalität ersetzt. Wo eine vollständige Neuimplementierung kurzfristig zu teuer ist, hilft ein Kompatibilitäts-Modul, das Knockout und RequireJS gezielt nur für die betroffene Seite oder Komponente nachlädt, während der Rest des Themes vollständig Hyvä-nativ bleibt.

Die Entscheidung "kurzfristig Knockout behalten" versus "vollständig ersetzen" hängt von drei Kriterien ab: Wie kritisch ist die Komponente für die Conversion (Checkout schlägt hier immer höher als eine Wunschlisten-Funktion), plant der Hersteller ohnehin ein Hyvä-natives Release, und wie hoch sind die Kosten einer Eigenentwicklung im Vergleich zum Wartungsaufwand der Kompatibilitätslösung. Bei checkout-nahen Komponenten ist Vorsicht immer die richtige Grundhaltung.

8. Migrations-Checkliste und Rollout-Strategie

Ein realistischer Rollout beginnt mit einer vollständigen Bestandsaufnahme: Ein Grep über alle Layout-XML-Dateien nach jsLayout, Magento_Ui/js/core/app und bekannten Knockout-Komponentenpfaden liefert eine Liste aller aktiven UI-Components im Shop. Jede Position wird nach Geschäftskritikalität eingestuft - Checkout, Warenkorb und Zahlungsschritte werden in dieser ersten Phase bewusst nicht angefasst, unabhängig davon, wie einfach die Migration technisch erscheint.

Die Reihenfolge folgt dem Risiko: Zuerst migriert man niedrigrisikoreiche Widgets wie Produktlisten-Sorter, Swatch-Renderer oder Vergleichsfunktion, jeweils Modul für Modul und mit klar abgegrenztem Layout-XML-Scope. Jede migrierte Komponente durchläuft vor dem Rollout einen Regressionstest entlang der wichtigsten Conversion-Schritte - Produkt ansehen, in den Warenkorb legen, Checkout starten - damit ein Alpine-Fehler nicht erst im Live-Betrieb auffällt.

Erst wenn alle nicht-kritischen UI-Components zuverlässig durch Hyvä-Templates ersetzt sind und sich das Team mit dem Mapping-Muster aus Abschnitt 3 vertraut gemacht hat, sollten checkout-nahe Komponenten angegangen werden - dann aber mit erweiterten End-to-End-Tests und einer klaren Rollback-Möglichkeit über Feature-Flags oder Layout-XML-Schalter.

9. Luma-UI-Component vs. Hyvä-Template im Vergleich

Die folgende Übersicht fasst die zentralen Unterschiede zwischen einer klassischen Luma-UI-Component und ihrem Hyvä-Template-Äquivalent zusammen. Der Unterschied ist keine Geschmacksfrage, sondern wirkt sich direkt auf Ladezeit, Wartbarkeit und Testbarkeit aus.

Wichtig ist, diese Tabelle nicht als Argument gegen Knockout im Allgemeinen zu lesen, sondern als Begründung für die Hyvä-spezifische Entscheidung: Auf der Storefront, wo jede Millisekunde Ladezeit direkt Conversion kostet, überwiegt der Aufwand der Migration bei Weitem den langfristigen Nutzen aus schlankerem JS, klarerem Datenfluss und einfacherer Testbarkeit.

10. Zusammenfassung

Die Ablösung von Luma-UI-Components durch native Hyvä-Templates ist kein kosmetisches Refactoring, sondern der Kern jeder ernsthaften Hyvä-Migration. Wer bestehende jsLayout-XML und ko-Templates sorgfältig liest, bevor er Code schreibt, versteht die tatsächliche Datenlogik hinter jedem Widget - und kann sie zielgerichtet auf eine ViewModel-plus-Alpine.data()-Struktur übertragen, statt Knockout-Fragmente notdürftig in ein neues Theme zu pressen.

Die vier Bindings visible, text, foreach und click decken die meisten Fälle ab und übersetzen sich direkt in x-show, x-text, x-for und x-on:click. Für Drittanbieter-Module, die noch nicht auf Hyvä-Templates umgestellt haben, braucht es eine bewusste Kompatibilitätsstrategie statt einer pauschalen Sofort-Migration - und für den Rollout gilt: unkritische Widgets zuerst, Checkout und Warenkorb zuletzt, immer mit Regressionstests zwischen jedem Migrationsschritt.

11. FAQ: Luma-UI-Components durch Hyvä-Templates ablösen