Luma-Module nach Hyvä portieren: Vorgehen, Aufwand, Praxis

1. Portierung oder Compatibility-Modul: eine Abgrenzung

Bevor man beginnt, ein Drittanbieter-Modul Hyvä-kompatibel zu machen, lohnt sich die Frage, ob eine vollständige Portierung überhaupt der richtige Weg ist. Ein Compatibility-Modul, das Luma-Assets isoliert lädt oder ein einfaches Fallback-Rendering bereitstellt, reicht als Übergangslösung, wenn das Modul selten genutzt wird, ohnehin bald ersetzt werden soll oder der Hersteller bereits an einer nativen Hyvä-Version arbeitet. Diese Entscheidung, ob Luma-Reste überhaupt entfernt werden müssen, ist Thema eines separaten Audits und wird hier bewusst nur kurz gestreift.

Wer ein Modul dauerhaft im Einsatz hat, Wert auf Performance und strikte CSP-Konformität legt oder das Frontend stark anpassen möchte, kommt an einer echten Portierung nicht vorbei. Genau darum geht es in diesem Artikel: das konkrete Vorgehen, um Luma-Module nach Hyvä zu portieren, von der Bestandsaufnahme über die Template-Übersetzung bis zur CSP-Absicherung, samt realistischer Aufwandsschätzung für unterschiedliche Modultypen.

2. Audit-Phase: Templates, Knockout-Bindings und Widgets identifizieren

Der erste Schritt, um ein Modul Hyvä-kompatibel zu machen, ist eine vollständige Bestandsaufnahme. Ohne diesen Audit unterschätzt man den Aufwand systematisch, weil Knockout-Bindings und RequireJS-Widgets oft tief in verschachtelten UI-Component-Konfigurationen versteckt sind. Ziel ist eine Liste aller .html-Templates, aller data-bind-Attribute, aller ko.observable-Aufrufe und aller RequireJS-Widget-Definitionen, die im Frontend des Drittanbieter-Moduls existieren.

Die Suche erfolgt am besten direkt im Modulverzeichnis mit gezielten grep-Befehlen. Wichtig ist, sowohl view/frontend/web/template als auch view/frontend/layout und view/frontend/requirejs-config.js abzudecken, da Knockout-Templates, Layout-Bindings und Widget-Registrierungen an unterschiedlichen Stellen liegen. Wer diesen Audit sorgfältig macht, bevor er beginnt, Luma-Module nach Hyvä zu portieren, vermeidet böse Überraschungen mitten in der Umsetzung.

#!/usr/bin/env bash
# audit-luma-module.sh - find Knockout bindings, observables and RequireJS widgets
# in a third-party Luma module before porting it to Hyva
set -euo pipefail

MODULE_DIR="app/code/Vendor/ThirdPartyModule"

echo "=== Knockout templates (.html) ==="
find "$MODULE_DIR" -path "*/web/template/*" -name "*.html"

echo "=== data-bind attributes ==="
grep -rn "data-bind=" "$MODULE_DIR" --include="*.html" --include="*.phtml"

echo "=== ko.observable / ko.observableArray usage ==="
grep -rn "ko\.observable\|ko\.computed\|ko\.observableArray" "$MODULE_DIR" --include="*.js"

echo "=== RequireJS widgets (jQuery UI widget factory) ==="
grep -rln "define(\['jquery'" "$MODULE_DIR" --include="*.js" \
  | xargs grep -l "widget(" || true

echo "=== UI Component XML declarations ==="
find "$MODULE_DIR" -path "*/ui_component/*" -name "*.xml"

echo "=== knockout templates referenced from layout XML ==="
grep -rn "Magento_Ui/js/lib/knockout\|uiComponent" "$MODULE_DIR" --include="*.xml"

3. Knockout-Templates in Alpine.js-phtml übersetzen

Der Kern jeder Arbeit, um Module Hyvä-kompatibel zu machen, ist die Übersetzung der Knockout-Templates. Ein .html-Template mit data-bind="visible: isActive" wird zu einem .phtml-Template mit x-show="isActive". Wichtig dabei: Alpine.js arbeitet direkt mit dem DOM statt mit einem virtuellen Bindings-Layer, deshalb wandert die Zustandslogik komplett in eine x-data-Definition am Wurzelelement, statt über einen separaten Knockout-ViewModel geladen zu werden.

Foreach-Bindings werden zu x-for mit <template>, click-Bindings zu @click, text-Bindings zu x-text. Die größte Umstellung betrifft die Datenquelle: Wo Knockout die Werte per AJAX in observables lud, liest Alpine.js die initialen Daten direkt aus PHP über json_encode() im Template und reichert sie bei Bedarf per fetch() an. Wer Luma-Module nach Hyvä portiert, sollte diese Übersetzung Template für Template dokumentieren, damit spätere Reviews nachvollziehbar bleiben.

<!-- BEFORE: Knockout/UI-Component template (view/frontend/web/template/widget.html) -->
<div data-bind="visible: isActive, css: { 'is-loading': isLoading() }">
  <span data-bind="text: itemCount"></span>
  <ul data-bind="foreach: items">
    <li data-bind="click: $parent.selectItem, text: label"></li>
  </ul>
  <button data-bind="click: loadMore, enable: !isLoading()">Load more</button>
</div>

<!-- AFTER: native Hyva phtml with Alpine.js -->
<?php /** @var \Magento\Framework\View\Element\Template $block */ ?>
<div x-data="thirdPartyWidget()" x-init="init()" :class="{ 'is-loading': isLoading }">
  <span x-text="itemCount"></span>
  <ul>
    <template x-for="item in items" :key="item.id">
      <li @click="selectItem(item)" x-text="item.label"></li>
    </template>
  </ul>
  <button @click="loadMore()" :disabled="isLoading">Load more</button>
</div>

4. RequireJS-Widgets durch Alpine-Komponenten ersetzen

Neben Templates enthalten viele Drittanbieter-Module RequireJS-Widgets nach dem jQuery-UI-Widget-Pattern ($.widget(...)). Um ein Modul vollständig Hyvä-kompatibel zu machen, müssen diese Widgets durch Alpine-Komponenten ersetzt werden, die über Alpine.data(...) registriert sind. Der Aufbau bleibt ähnlich: Optionen werden zu reaktiven Properties, Widget-Methoden werden zu Alpine-Methoden, und die Initialisierung erfolgt über init() statt über _create().

Ein wichtiger Unterschied: RequireJS-Widgets binden sich per Selektor an beliebige DOM-Elemente, während Alpine-Komponenten deklarativ über x-data im Template verankert werden. Events, die das Widget früher per this._trigger(...) auslöste, werden zu $dispatch(...)-Aufrufen mit einem eigenen Namespace, damit sie nicht mit Hyvä-Core-Events kollidieren. Wer Luma-Module nach Hyvä portiert, sollte jede Widget-Option explizit als Alpine-Property dokumentieren, damit die Übersetzung vollständig bleibt.

// BEFORE: RequireJS / jQuery UI widget factory
define(['jquery', 'jquery/ui'], function ($) {
  'use strict';
  $.widget('vendor.thirdPartyWidget', {
    options: { autoRefresh: true, refreshInterval: 5000 },
    _create: function () {
      this.isLoading = false;
      this._bindEvents();
      if (this.options.autoRefresh) {
        this._startPolling();
      }
    },
    _bindEvents: function () {
      this.element.on('click', '.js-refresh', $.proxy(this._refresh, this));
    },
    _refresh: function () {
      this.isLoading = true;
      this._trigger('refreshStart');
      // ... ajax call ...
    }
  });
  return $.vendor.thirdPartyWidget;
});

// AFTER: Alpine.js component registered via Alpine.data
document.addEventListener('alpine:init', () => {
  Alpine.data('thirdPartyWidget', (autoRefresh = true, refreshInterval = 5000) => ({
    isLoading: false,
    autoRefresh: autoRefresh,
    refreshInterval: refreshInterval,

    init() {
      if (this.autoRefresh) {
        this.startPolling();
      }
    },
    refresh() {
      this.isLoading = true;
      this.$dispatch('vendor:refresh-start');
      // ... fetch call ...
    },
    startPolling() {
      setInterval(() => this.refresh(), this.refreshInterval);
    }
  }));
});

5. LESS/CSS zu Tailwind-Utilities migrieren

Nachdem Templates und Widgets portiert sind, bleibt das Styling. Drittanbieter-Module bringen meist eigene LESS-Dateien mit, die im Hyvä-Theme weder geladen noch benötigt werden. Um ein Modul konsequent Hyvä-kompatibel zu machen, werden LESS-Klassen durch Tailwind-Utility-Klassen direkt im Template ersetzt. Eigene CSS-Regeln mit festen Farbwerten, Abständen und Breakpoints entfallen fast vollständig zugunsten von Utility-Klassen wie flex, gap-4 oder rounded-lg.

@apply sollte dabei sparsam eingesetzt werden, nur für wirklich wiederkehrende Komponenten-Muster, die an vielen Stellen identisch vorkommen. Für alles andere gilt: Utility-Klassen direkt im Markup sind in Tailwind CSS v4 der bevorzugte Weg, weil sie ohne zusätzliche CSS-Datei auskommen und der Build-Prozess ungenutzte Klassen automatisch entfernt. Wer Luma-Module nach Hyvä portiert, sollte die alte LESS-Datei erst löschen, nachdem alle Klassen im Template ersetzt sind, um versehentliche Restabhängigkeiten zu vermeiden.

/* BEFORE: module LESS file (view/frontend/web/css/source/_widget.less) */
.vendor-widget {
  display: flex;
  gap: 16px;
  padding: 24px;
  border-radius: 8px;
  background-color: #f8fafc;
  border: 1px solid #e2e8f0;
}
.vendor-widget__title {
  font-size: 18px;
  font-weight: 700;
  color: #0f172a;
  margin-bottom: 8px;
}
.vendor-widget.is-loading {
  opacity: 0.5;
  pointer-events: none;
}

/* AFTER: equivalent Tailwind utility classes used directly in the phtml template */
/* <div class="flex gap-4 p-6 rounded-lg bg-slate-50 border border-slate-200"
        :class="{ 'opacity-50 pointer-events-none': isLoading }">
     <p class="text-lg font-bold text-slate-900 mb-2">...</p>
   </div> */

/* @apply used sparingly, only for a truly repeated pattern */
.widget-card {
  @apply flex gap-4 p-6 rounded-lg bg-slate-50 border border-slate-200;
}

6. Formulare und Validierung ohne Knockout

Viele Drittanbieter-Module bringen eigene Formulare mit, deren Validierung komplett über Knockout-Computed-Observables läuft. Um ein Formular Hyvä-kompatibel zu machen, ersetzt man diese Logik durch native HTML5-Validierung (required, pattern, minlength) kombiniert mit Alpine.js x-data für dynamisches Verhalten wie bedingte Felder oder Live-Feedback. Das reduziert JavaScript-Code drastisch, weil der Browser einen Großteil der Validierungslogik selbst übernimmt.

Für Fälle, die über native Validierung hinausgehen, etwa Server-Side-Checks oder komplexe Feldabhängigkeiten, übernimmt Alpine.js die Orchestrierung: Ein x-data-Objekt hält den Formularzustand, @submit.prevent fängt das Absenden ab, prüft form.checkValidity() und zeigt bei Bedarf eigene Fehlermeldungen. Diese Kombination ist bei Formularen, die man nach Hyvä portiert, deutlich robuster als der Versuch, Knockout-Validierung eins zu eins nachzubauen.

<?php /** @var \Magento\Framework\View\Element\Template $block */ ?>
<form x-data="thirdPartyForm()" @submit.prevent="submitForm($event)" novalidate>
  <div class="mb-4">
    <label class="block text-sm font-semibold mb-1" for="vendor_email">Email</label>
    <input
      id="vendor_email"
      type="email"
      name="vendor_email"
      class="border rounded-lg px-3 py-2 w-full"
      required
      x-model="email"
      :class="{ 'border-red-500': errors.email }"
    >
    <p class="text-red-600 text-xs mt-1" x-show="errors.email" x-text="errors.email"></p>
  </div>

  <div class="mb-4" x-show="requiresPhone">
    <label class="block text-sm font-semibold mb-1" for="vendor_phone">Phone</label>
    <input id="vendor_phone" type="tel" name="vendor_phone" class="border rounded-lg px-3 py-2 w-full"
           pattern="[0-9+ ]{6,}" x-model="phone" :required="requiresPhone">
  </div>

  <button type="submit" class="bg-orange-600 text-white font-semibold px-4 py-2 rounded-lg" :disabled="isSubmitting">
    Submit
  </button>
</form>

<script>
document.addEventListener('alpine:init', () => {
  Alpine.data('thirdPartyForm', () => ({
    email: '',
    phone: '',
    requiresPhone: false,
    isSubmitting: false,
    errors: {},
    submitForm(event) {
      if (!event.target.checkValidity()) {
        event.target.reportValidity();
        return;
      }
      this.isSubmitting = true;
      // ... fetch to controller endpoint ...
    }
  }));
});
</script>

7. CSP-Konformität sicherstellen

Hyvä läuft standardmäßig mit einer strikten Content-Security-Policy, und jedes verbleibende Inline-<script> muss dafür registriert werden. Wer ein Modul Hyvä-kompatibel machen will, darf diesen Schritt nicht vergessen: Direkt nach jedem Inline-Script-Block folgt der Aufruf von $hyvaCsp->registerInlineScript() im .phtml-Template. Ohne diese Registrierung blockiert der Browser das Skript, und die Alpine-Komponente initialisiert sich nicht, was sich meist erst spät im Testing bemerkbar macht.

Für Skripte, die aus dem ursprünglichen Drittanbieter-Modul stammen und externe Inline-Handler wie onclick="..." nutzen, reicht die Registrierung allein nicht: Diese Attribute müssen zuerst in @click-Direktiven umgewandelt werden, weil CSP inline Event-Handler grundsätzlich blockiert, unabhängig von Nonce oder Hash. Für Third-Party-Skripte, die nicht entfernt werden können, etwa ein externes Tracking-Snippet, kommt statt eines Nonce meist eine Hash-Liste in csp_whitelist.xml zum Einsatz, da sich Nonces bei jedem Request ändern und für statische externe Assets ungeeignet sind.

8. Aufwandsschätzung: klein, mittel, groß

Der Aufwand, ein Modul Hyvä-kompatibel zu machen, hängt fast ausschließlich davon ab, wie viel Zustandslogik und wie viele Interaktionen das Frontend enthält, nicht von der reinen Codemenge. Ein reines Anzeige-Widget ohne eigene Formulare und ohne AJAX-Nachladen liegt meist bei 0,5 bis 1,5 Personentagen: Template übersetzen, Styles migrieren, CSP registrieren. Ein Modul mittlerer Komplexität mit einem Formular, clientseitiger Validierung und einem AJAX-Request bewegt sich realistisch zwischen 2 und 4 Personentagen.

Komplexe Module mit Checkout-Integration, mehreren miteinander kommunizierenden UI-Components oder einem eigenen Dashboard mit mehreren Ansichten liegen häufig bei 5 bis 10 Personentagen oder mehr. Die stärksten Kostentreiber sind: die Anzahl verschachtelter Knockout-Bindings pro Template, versteckte Abhängigkeiten zu Magento_Ui-Komponenten, serverseitige Endpunkte, die zusätzlich angepasst werden müssen, und fehlende oder veraltete Dokumentation des Drittanbieter-Moduls. Wer Luma-Module nach Hyvä portiert, sollte den Audit aus Abschnitt 2 nutzen, um diese Faktoren vor der Aufwandsschätzung konkret zu zählen, statt grob zu schätzen.

9. Vergleichstabelle: Zeitaufwand und Risiko je Modultyp

Die folgende Übersicht ordnet typische Drittanbieter-Modultypen nach Zeitaufwand, Risiko und empfohlenem Vorgehen ein. Sie ersetzt keine individuelle Aufwandsschätzung, gibt aber eine belastbare erste Orientierung, bevor man entscheidet, ein konkretes Modul nach Hyvä zu portieren.

Auffällig ist, dass Risiko und Aufwand fast immer zusammen steigen, sobald ein Modul in Checkout-Prozesse eingreift oder mehrere UI-Components miteinander synchronisiert. Für diese Fälle lohnt sich vor der eigentlichen Portierung ein kurzer Proof-of-Concept an einer einzelnen, isolierten Komponente, um die tatsächliche Komplexität zu validieren, bevor der volle Aufwand budgetiert wird.

10. Zusammenfassung

Ein Drittanbieter-Modul Hyvä-kompatibel zu machen ist ein klar strukturierbares Vorgehen, kein Blackbox-Projekt: Zuerst ein sauberer Audit aller Knockout-Bindings, RequireJS-Widgets und LESS-Dateien. Danach werden Templates Schritt für Schritt von data-bind zu x-show/x-for/x-text übersetzt, Widgets wandern von $.widget(...) zu Alpine.data(...), und Styles wechseln von eigenen LESS-Regeln zu Tailwind-Utilities. Formulare nutzen native HTML5-Validierung kombiniert mit Alpine.js für dynamisches Verhalten. Jedes verbleibende Inline-Script wird mit $hyvaCsp->registerInlineScript() abgesichert.

Der Aufwand, Luma-Module nach Hyvä zu portieren, hängt vor allem von der Menge an Zustandslogik und Interaktionen ab: von einem halben Tag für ein reines Anzeige-Widget bis zu mehreren Wochen für ein komplexes Checkout-Feature mit mehreren UI-Components. Ein kurzer Proof-of-Concept vor der vollen Portierung hilft, die Aufwandsschätzung realistisch zu kalibrieren, statt auf Basis der reinen Codemenge zu schätzen.

11. FAQ: Luma-Module nach Hyvä portieren