Hyvä-Migration: Von Luma zu Hyvä, Strategie und Stolperfallen

1. Warum Shops von Luma zu Hyvä wechseln

Die Hyvä-Migration steht bei den meisten Magento-Betreibern aus einem einzigen Grund ganz oben auf der Roadmap: Performance. Ein klassisches Luma-Theme lädt RequireJS-Bundles, initialisiert Knockout.js-Komponenten und hydriert Data-Bindings, bevor eine Seite tatsächlich interaktiv wird. Diese Hydration-Phase ist auf Mobilgeräten mit schwächerer CPU besonders spürbar und schlägt sich direkt in der Time to Interactive nieder, einer Kernmetrik für Core Web Vitals und damit auch für die Sichtbarkeit in Suchmaschinen. Ein Hyvä-Theme verzichtet komplett auf Knockout.js und RequireJS-Bundle-Overhead und liefert stattdessen serverseitig gerendertes HTML, das nur dort interaktiv wird, wo es Alpine.js-Komponenten wirklich braucht.

Der zweite Treiber hinter jeder Hyvä-Migration ist die Wartbarkeit. Luma-Themes bauen auf LESS und einer tief verschachtelten UI-Component-Struktur auf, bei der eine kleine Anpassung im Checkout schnell mehrere XML-Dateien, ein JS-Modul und ein Knockout-Template gleichzeitig betrifft. Tailwind CSS v4 ersetzt diese Struktur durch Utility-Klassen direkt im Template, wodurch Styling und Markup an derselben Stelle sichtbar bleiben und neue Entwickler sich ohne Einarbeitung in die LESS-Kaskade zurechtfinden. In Kombination mit Alpine.js als einzigem JS-Layer sinkt die Zahl der Abstraktionsebenen spürbar, was sich in kürzeren Entwicklungszeiten für jedes weitere Feature niederschlägt.

2. Phase 1: Audit des bestehenden Luma-Themes

Jede seriöse Hyvä-Migration beginnt mit einem vollständigen Audit des bestehenden Luma-Themes, nicht mit dem Aufsetzen eines neuen Theme-Ordners. Im ersten Schritt wird jede installierte Extension daraufhin geprüft, ob sie eigene UI-Components registriert, Knockout-Widgets über requirejs-config.js einbindet oder Layout-XML-Handles überschreibt, die im Checkout oder auf der Kategorieseite greifen. Ein einfaches, aber wirkungsvolles Vorgehen ist die Suche nach ui_component-Deklarationen in view/frontend/ui_component sowie nach .js-Dateien, die ko.observable oder uiComponent importieren, über alle app/code- und vendor-Verzeichnisse hinweg.

Im zweiten Schritt des Audits werden alle Checkout-Anpassungen dokumentiert, da sie in der Hyvä-Migration erfahrungsgemäß den größten Einzelposten darstellen. Dazu gehören zusätzliche Checkout-Steps, individuelle Zahlungsart-Renderer, angepasste Adressvalidierung und jede Stelle, an der Magento_Checkout/js/model/step-navigator referenziert wird. Ergänzend lohnt sich ein Blick in etc/frontend/di.xml und view/frontend/layout jeder Extension, weil dort sichtbar wird, welche Blöcke tatsächlich im Frontend gerendert werden und welche nur inaktiver Legacy-Code sind. Das Ergebnis dieses Audits ist eine priorisierte Liste aller Komponenten, die für die spätere Aufwandsschätzung und die Phasenplanung der Hyvä-Migration benötigt wird.

3. Phase 2: Hyvä-Compatibility-Module identifizieren

Sobald das Audit steht, folgt der Abgleich mit verfügbaren Hyvä-Compatibility-Modulen. Für viele verbreitete Drittanbieter-Extensions existieren bereits fertige hyva-themes/magento2-*-compat-Pakete, die Knockout-basierte Frontend-Teile durch Alpine.js-Äquivalente ersetzen, ohne dass die Business-Logik der Extension selbst angefasst werden muss. Diese Pakete werden regulär per Composer eingebunden und ersetzen über Modul-Sequencing gezielt die Frontend-Templates der Ursprungs-Extension. Vor der Hyvä-Migration lohnt sich daher immer zuerst eine Recherche auf Packagist und im offiziellen Hyvä-Compatibility-Modul-Verzeichnis, bevor Eigenentwicklung eingeplant wird.

Fehlt ein Compatibility-Modul für eine geschäftskritische Extension, bleibt nur die Eigenentwicklung eines schlanken Kompatibilitätsmoduls nach demselben Muster: Templates der Zielextension per view/frontend/layout überschreiben und Knockout-Bindings durch Alpine.js-Komponenten ersetzen. Diese Entscheidung, Compatibility-Modul einbinden versus Eigenentwicklung, ist der größte Hebel für die Projektlaufzeit einer Hyvä-Migration, weil Eigenentwicklung Testaufwand für jede betroffene Extension nach sich zieht.

{
  "require": {
    "hyva-themes/magento2-default-theme-csp": "^1.3",
    "hyva-themes/magento2-amasty-shopby-compat": "^2.0",
    "hyva-themes/magento2-mageplaza-compat": "^1.2",
    "hyva-themes/magento2-mirasvit-compat": "^1.0"
  },
  "extra": {
    "magento-force": "override"
  }
}

4. Phase 3: Theme-Grundgerüst und Tailwind-Design-System

Das Theme-Grundgerüst der Hyvä-Migration entsteht als Kind-Theme von hyva-themes/magento2-default-theme-csp, angelegt unter app/design/frontend/Vendor/default mit eigener registration.php und theme.xml. Statt bei null zu beginnen, wird das bestehende Corporate Design aus dem Luma-Theme extrahiert: Farbwerte aus den LESS-Variablen, Schriftgrößen aus der Typography-Konfiguration und Abstandsraster aus den vorhandenen Grid-Definitionen werden in tailwind.config.js beziehungsweise in die CSS-First-Konfiguration von Tailwind v4 übertragen. So bleibt das Erscheinungsbild für Kunden nahezu unverändert, während im Hintergrund die komplette Rendering-Technologie ausgetauscht wird.

Ein häufig unterschätzter Teil dieser Phase ist die Übertragung von Design-Tokens, die in Luma über mehrere LESS-Dateien verstreut waren, etwa Primärfarbe, Fehlerfarbe und Rahmenradien, in ein zentrales Tailwind-Theme-Objekt. Diese Konsolidierung zahlt sich später mehrfach aus, weil jede weitere Anpassung nur noch an einer Stelle erfolgt. Für Komponenten, die visuell identisch bleiben sollen, aber technisch neu aufgebaut werden, wie Produktkarten, Mini-Cart oder Facetten-Filter, wird in dieser Phase der Hyvä-Migration jeweils ein Alpine.js-Grundgerüst erstellt, das später in Phase vier mit den echten Daten aus den GraphQL- beziehungsweise Block-Quellen befüllt wird.

5. Aufwandsschätzung: Projektgrößen und Kostentreiber

Der Aufwand einer Hyvä-Migration hängt fast ausschließlich von drei Variablen ab: der Zahl der Drittanbieter-Extensions ohne fertiges Compatibility-Modul, dem Umfang individueller Checkout-Anpassungen und der Menge an Custom-UI-Components im bestehenden Luma-Theme. Ein Standard-Shop mit Standard-Checkout und wenigen, gut unterstützten Extensions lässt sich in überschaubarer Zeit migrieren, weil Theme-Grundgerüst, Kategorie- und Produktseite weitgehend aus dem Hyvä-Default-Theme übernommen werden können und nur Corporate-Design-Anpassungen hinzukommen.

Deutlich aufwendiger wird eine Hyvä-Migration, sobald ein individueller Checkout mit eigenen Steps, eigener Zahlungsart-Logik oder komplexer Adressvalidierung vorhanden ist, da hier praktisch jede Knockout-Komponente einzeln als Alpine.js-Komponente neu gebaut und gegen echte Bestellungen getestet werden muss. Am stärksten steigt der Aufwand jedoch bei Shops mit vielen Drittanbieter-Extensions ohne offizielles Compatibility-Modul, etwa spezialisierten B2B-Preislisten-Modulen oder individuellen Konfigurator-Widgets, weil hier für jede Extension einzeln entschieden werden muss, ob ein Compatibility-Modul erstellt oder die Funktion in der neuen Architektur nachgebaut wird. In der Praxis empfiehlt sich deshalb immer erst das vollständige Audit aus Phase eins, bevor ein belastbares Angebot für die Hyvä-Migration erstellt wird.

6. Stolperfalle 1: Custom-Checkout-Steps auf Knockout-Basis

Die häufigste technische Stolperfalle einer Hyvä-Migration sind individuelle Checkout-Steps, die tief in die Knockout.js-Komponentenstruktur von Magento_Checkout eingreifen. Ein Step, der über stepNavigator.registerStep registriert wird und eigene Observables für Formularfelder führt, hat in Hyvä keine direkte Entsprechung, weil weder uiComponent noch ko.observable im Hyvä-Checkout zur Verfügung stehen. Diese Steps müssen komplett neu als Alpine.js-Komponenten gebaut werden, inklusive eigener State-Verwaltung und eigener Kommunikation mit der Checkout-REST-API oder GraphQL-Mutation.

Im folgenden Vergleich zeigt sich, wie sich ein einfacher Zusatz-Step für Lieferhinweise von der Knockout-Variante in Luma zur Alpine.js-Variante in Hyvä verändert. In Luma wird der Step über ein JS-Modul registriert und bindet Formularwerte über data-bind an ein Observable, während in Hyvä dieselbe Funktion direkt im phtml-Template mit x-data und einem einfachen fetch-Aufruf gegen die Checkout-REST-API abgebildet wird.

// BEFORE (Luma): Vendor_DeliveryNotes/view/frontend/web/js/view/delivery-notes.js
define([
  'uiComponent',
  'Magento_Checkout/js/model/step-navigator',
  'ko'
], function (Component, stepNavigator, ko) {
  'use strict';
  return Component.extend({
    defaults: {
      template: 'Vendor_DeliveryNotes/delivery-notes'
    },
    deliveryNote: ko.observable(''),

    initialize: function () {
      this._super();
      stepNavigator.registerStep(
        'delivery-notes',
        null,
        $t('Delivery Notes'),
        this.isVisible,
        this.navigate
      );
      return this;
    },

    saveNote: function () {
      return fetch('/rest/V1/carts/mine/delivery-note', {
        method: 'PUT',
        body: JSON.stringify({ note: this.deliveryNote() })
      });
    }
  });
});

<!-- AFTER (Hyvä): view/frontend/templates/checkout/delivery-notes.phtml -->
<div x-data="deliveryNotes()" class="mb-6 border border-gray-200 rounded-lg p-4">
    <label class="block text-sm font-medium text-gray-700 mb-2">Delivery Notes</label>
    <textarea
        x-model="note"
        @input.debounce.400ms="persist()"
        class="w-full rounded-lg border-gray-300 text-sm"
        rows="3"
    ></textarea>
    <p class="text-xs text-gray-500 mt-1" x-show="saved">Saved</p>
</div>

<script>
    function deliveryNotes() {
        return {
            note: '',
            saved: false,
            persist() {
                fetch('/rest/V1/carts/mine/delivery-note', {
                    method: 'PUT',
                    headers: { 'Content-Type': 'application/json' },
                    body: JSON.stringify({ note: this.note })
                }).then(() => { this.saved = true; });
            }
        };
    }
</script>

7. Stolperfalle 2: jQuery-Widget-Abhängigkeiten

Die zweite typische Stolperfalle einer Hyvä-Migration betrifft Drittanbieter-Module, die intern auf jQuery-Widgets setzen, etwa $.widget-basierte Datepicker, Slider oder Tab-Komponenten. Hyvä lädt jQuery bewusst nicht global, weil genau dieser Bundle-Overhead einer der Hauptgründe für die schlechtere Time to Interactive in Luma war. Ein Modul, das per RequireJS-Shim auf jquery/ui zugreift, lädt in Hyvä entweder gar nicht oder wirft in der Browser-Konsole einen $ is not defined-Fehler, sobald das zugehörige Skript ausgeführt wird.

Für diese Fälle gibt es in der Hyvä-Migration drei gangbare Wege: Erstens die Suche nach einem passenden Compatibility-Modul, das die jQuery-Abhängigkeit bereits durch Alpine.js ersetzt. Zweitens der Eigenbau einer schlanken Alpine.js-Komponente, die dieselbe UI-Funktion ohne jQuery abbildet, was bei einfachen Widgets wie Tabs oder Akkordeons meist wenig Aufwand bedeutet. Drittens, als letzte Option und nur für geschäftskritische Fälle ohne Alternative, das gezielte Nachladen von jQuery ausschließlich auf der betroffenen Seite über ein eigenes RequireJS-Modul mit CSP-konformem Nonce. Diese dritte Option sollte in jeder Hyvä-Migration die Ausnahme bleiben, da sie einen Teil des ursprünglichen Performance-Gewinns wieder zunichtemacht.

8. Stolperfalle 3: CSP-Konformität bei migrierten Inline-Scripts

Die dritte häufige Stolperfalle betrifft die Content Security Policy. Hyvä liefert standardmäßig ein striktes CSP-Modul aus, das Inline-Scripts ohne gültigen Nonce blockiert. Wer bei der Hyvä-Migration Alpine.js-Komponenten schreibt und dabei einfach ein <script>-Tag ohne weitere Behandlung in ein phtml-Template kopiert, sieht die Funktion im Frontend nicht ausgeführt und erhält in der Browser-Konsole eine CSP-Verletzung. Die Lösung ist das ViewModel Hyva\Theme\ViewModel\HyvaCsp, das nach jedem Inline-Script-Block aufgerufen werden muss und den passenden Nonce für die aktuelle Anfrage in das Script injiziert.

Diese Regel gilt ausnahmslos für jeden migrierten Inline-Block, egal ob er aus einem Luma-Template stammt oder komplett neu für die Hyvä-Migration geschrieben wurde. Fehlt der Aufruf von registerInlineScript(), funktioniert die Komponente in der lokalen Entwicklungsumgebung mit deaktivierter CSP oft trotzdem, bricht aber sofort, sobald die CSP-Konfiguration in der Staging- oder Produktivumgebung aktiv geschaltet wird. Genau dieser Unterschied zwischen lokaler und produktiver CSP-Konfiguration ist die häufigste Ursache für spät entdeckte Bugs nach dem Go-Live.

<?php
/** @var \Hyva\Theme\ViewModel\HyvaCsp $hyvaCsp */
$hyvaCsp = $viewModels->require(\Hyva\Theme\ViewModel\HyvaCsp::class);
?>
<div x-data="stockNotification()" class="mt-4">
    <button
        @click="subscribe()"
        class="rounded-lg bg-orange-600 text-white text-sm font-semibold px-4 py-2"
        x-text="subscribed ? 'Subscribed' : 'Notify me'"
    ></button>
</div>

<script>
    function stockNotification() {
        return {
            subscribed: false,
            subscribe() {
                fetch('/rest/V1/stock-notifications', { method: 'POST' })
                    .then(() => { this.subscribed = true; });
            }
        };
    }
</script>
<?= $hyvaCsp->registerInlineScript() ?>

9. Rollout-Strategie: Staging, A/B-Test und Etappen

Ein Big-Bang-Umschalten von Luma auf Hyvä an einem einzigen Wochenende ist bei umsatzstarken Shops selten die richtige Wahl. Bewährt hat sich stattdessen eine etappenweise Hyvä-Migration, bei der zuerst wenig kritische Seitentypen wie CMS-Seiten und Kategorieseiten live gehen, während der Checkout bis zuletzt auf dem gut getesteten Luma-Theme verbleibt. Vor jedem Rollout-Schritt läuft ein vollständiger Vergleich auf einer Staging-Umgebung, bei dem Kernfunktionen wie Warenkorb, Gutscheincode-Einlösung und Zahlungsabwicklung gegen das bestehende Luma-Theme abgeglichen werden.

Für risikoärmere Shops eignet sich zusätzlich ein A/B-Test über eine zweite Store View, bei der ein Teil des Traffics testweise das neue Hyvä-Theme ausgeliefert bekommt, während Conversion-Rate, Absprungrate und Time to Interactive live gegen die Luma-Kontrollgruppe gemessen werden. Erst wenn diese Kennzahlen über mehrere Wochen stabil positiv ausfallen, folgt die vollständige Umstellung inklusive Checkout. Diese Vorsicht zahlt sich bei jeder Hyvä-Migration aus, weil sie Umsatzrisiken durch unentdeckte Kompatibilitätsprobleme deutlich reduziert.

{
  "rollout_plan": {
    "phase_1_cms_and_category": {
      "page_types": ["cms_page", "catalog_category_view"],
      "store_views": ["default"],
      "traffic_percentage": 100,
      "rollback_trigger": "error_rate > 1%"
    },
    "phase_2_product_page": {
      "page_types": ["catalog_product_view"],
      "store_views": ["default"],
      "traffic_percentage": 50,
      "rollback_trigger": "add_to_cart_rate drop > 5%"
    },
    "phase_3_cart_and_checkout": {
      "page_types": ["checkout_cart_index", "checkout_index_index"],
      "store_views": ["default"],
      "traffic_percentage": 10,
      "rollback_trigger": "checkout_completion_rate drop > 2%"
    },
    "phase_4_full_rollout": {
      "page_types": ["all"],
      "store_views": ["default", "b2b", "eu"],
      "traffic_percentage": 100,
      "rollback_trigger": "none, monitoring only"
    }
  }
}

10. Zusammenfassung

Eine erfolgreiche Hyvä-Migration folgt einem klaren Vier-Phasen-Modell: Audit des bestehenden Luma-Themes, Abgleich mit verfügbaren Compatibility-Modulen, Aufbau des Theme-Grundgerüsts mit übertragenem Tailwind-Design-System und schließlich ein etappenweiser Rollout mit Staging-Vergleich und optionalem A/B-Test. Der Performance-Gewinn entsteht durch den Wegfall der Knockout.js-Hydration und des RequireJS-Bundle-Overheads, der Wartbarkeitsgewinn durch Tailwind CSS v4 anstelle der LESS-Kaskade und der UI-Component-Struktur.

Die drei häufigsten Stolperfallen, Custom-Checkout-Steps auf Knockout-Basis, jQuery-Widget-Abhängigkeiten aus Drittanbieter-Modulen und fehlende CSP-Konformität bei migrierten Inline-Scripts, lassen sich mit dem richtigen Vorgehen aus dieser Übersicht früh erkennen und einplanen, statt sie erst kurz vor dem Go-Live zu entdecken. Wer den Aufwand realistisch einschätzt und die Rollout-Etappen konsequent einhält, reduziert das Risiko einer Hyvä-Migration auf ein für den laufenden Shopbetrieb vertretbares Maß.

11. FAQ: Hyvä-Migration von Luma