Compatibility-Module verstehen: Luma-Reste im Hyvä-Shop richtig bewerten

1. Was Compatibility-Module technisch leisten

Ein Compatibility-Modul in Hyvä aktiviert einen Fallback-Rendering-Pfad für Drittanbieter-Module, die noch nicht auf native Hyvä-Templates portiert wurden. Statt das Frontend komplett auf Luma-Layout, Luma-CSS und RequireJS-Widgets umzustellen, lädt Hyvä für genau diese Module gezielt die alten Luma-Templates nach, während der Rest des Shops vollständig auf Tailwind und Alpine.js läuft. Das ist ein pragmatischer Kompromiss, kein Designfehler.

Das Problem entsteht, wenn Compatibility-Module unreflektiert für ganze Modulgruppen aktiviert werden, statt gezielt für die Module, die tatsächlich Frontend-Rendering betreiben. Jedes zusätzliche Compatibility-Modul zieht potenziell RequireJS, jQuery-Widgets und Luma-CSS-Bundles nach, selbst wenn das zugehörige Drittanbieter-Modul nur einen Admin-Grid rendert oder einen Cronjob ausführt. Wer Compatibility-Module nicht gezielt auditiert, sammelt über die Zeit Rendering-Pfade an, die niemand mehr braucht, aber jede Seite mitschleppt.

2. Welche Luma-Reste im Hintergrund aktiv bleiben

In jedem Hyvä-Shop bleiben strukturell einige Luma-Bereiche aktiv, unabhängig davon, wie konsequent das Frontend portiert wurde. Der Admin-Bereich läuft vollständig auf Luma und UI-Components, das betrifft die Frontend-Performance jedoch nicht, weil er nie an Kunden ausgeliefert wird. Relevant für Compatibility-Module sind andere Reste: RequireJS-Mixins von Drittanbietern, die sich an Luma-Komponenten hängen, der CSP-Report-Controller, der weiterhin Luma-Routen nutzt, und bestimmte Zahlungs-Iframes, die zwingend eigenes JavaScript mitbringen.

Ein typisches Compatibility-Modul registriert in seiner di.xml gezielt, für welche Frontend-Bereiche der Luma-Fallback greifen soll. Diese Konfiguration ist der erste Ort, an dem ein Audit ansetzt, weil sie sichtbar macht, welche Bereiche das Modul überhaupt beansprucht.

<?xml version="1.0"?>
<!-- app/code/Vendor/Module/etc/di.xml -->
<!-- Example: compatibility module scoping the Luma fallback -->
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">

    <!-- Fallback is limited to the checkout payment step only -->
    <type name="Hyva\Compat\Model\FallbackResolver">
        <arguments>
            <argument name="scopedModules" xsi:type="array">
                <item name="Vendor_PaymentGateway" xsi:type="array">
                    <item name="handles" xsi:type="array">
                        <item name="checkout_index_index" xsi:type="string">checkout_index_index</item>
                    </item>
                    <item name="blocks" xsi:type="array">
                        <item name="payment.iframe" xsi:type="string">Vendor\PaymentGateway\Block\Iframe</item>
                    </item>
                </item>
            </argument>
        </arguments>
    </type>
</config>

Diese enge Zuordnung ist der Unterschied zwischen einem sinnvollen und einem verschwenderischen Compatibility-Modul: Es sollte immer nur den konkreten Layout-Handle und die konkreten Blöcke referenzieren, die tatsächlich Luma-Fallback benötigen, statt pauschal ganze Module oder Routen auf Luma umzuschalten.

3. Entscheidungskriterium: ein Modul auditieren

Bevor man entscheidet, ob ein Compatibility-Modul überhaupt aktiv bleiben muss, sollte man prüfen, ob das zugrunde liegende Drittanbieter-Modul tatsächlich Frontend-Rendering betreibt. Viele Module registrieren zwar Layout-Handles, greifen aber nur im Admin-Bereich oder in Cron-Jobs ein. Das lässt sich mit ein paar gezielten grep-Abfragen über view/frontend, layout und requirejs-config.js klären, ohne den kompletten Modulcode lesen zu müssen.

Der Audit-Prozess läuft in drei Schritten: Layout-Handles im Frontend-Bereich finden, Blocknamen daraus extrahieren und mit dem tatsächlichen Seitenaufbau abgleichen, und schließlich prüfen, ob RequireJS-Abhängigkeiten überhaupt geladen werden. Nur wenn alle drei Fragen ein klares "ja" liefern, rechtfertigt das Modul ein aktives Compatibility-Modul.

#!/usr/bin/env bash
# audit-module.sh - check if a third-party module has real frontend rendering
set -euo pipefail

MODULE_PATH="app/code/Vendor/ReviewsModule"

echo "== Frontend layout handles =="
grep -rl "layout" "$MODULE_PATH/view/frontend/layout" 2>/dev/null || echo "none found"

echo "== Block classes referenced in frontend layout =="
grep -roE 'class="[A-Za-z0-9_\\\\]+"' "$MODULE_PATH/view/frontend/layout" 2>/dev/null | sort -u

echo "== RequireJS dependencies declared by this module =="
grep -rn "define(" "$MODULE_PATH/view/frontend/web/js" 2>/dev/null

echo "== Is the module referenced by requirejs-config.js anywhere? =="
grep -rn "Vendor_ReviewsModule" app/design/frontend/*/*/*/requirejs-config.js 2>/dev/null || echo "no explicit mixin found"

echo "== Templates that actually get rendered (phtml files) =="
find "$MODULE_PATH/view/frontend/templates" -name "*.phtml" 2>/dev/null

Liefert dieser Audit keine Frontend-Layout-Handles, keine referenzierten Blocknamen und keine ladbaren RequireJS-Module, hat das Modul faktisch keine sichtbare Beteiligung am Kunden-Frontend. In diesem Fall ist das zugehörige Compatibility-Modul reiner Ballast und kann deaktiviert werden, ohne dass sich am sichtbaren Verhalten des Shops etwas ändert.

4. Iframe-Isolation für unvermeidbare Luma-Fragmente

Manche Luma-Fragmente lassen sich nicht auditieren, weil sie schlicht zwingend erforderlich bleiben. Bestimmte Zahlungs-Widgets liefern eigenes JavaScript und eigenes CSS aus, das vom Zahlungsanbieter kontrolliert wird und nicht in Tailwind- oder Alpine.js-Konventionen überführbar ist. In solchen Fällen ist ein Compatibility-Modul nicht die eigentliche Lösung, sondern nur der Transportweg, der das Fragment überhaupt in die Seite bringt. Die eigentliche Isolation muss auf Rendering-Ebene passieren.

Ein iframe mit gesetztem sandbox-Attribut kapselt das Luma-Fragment vollständig: eigenes CSS kollidiert nicht mit dem Hyvä-Tailwind-Stylesheet, eigenes JavaScript läuft in einem isolierten Kontext und kann keine globalen Alpine.js-Komponenten oder CSP-Regeln der Hauptseite verletzen. Für Zahlungs-Iframes ist das oft die einzige praxistaugliche Lösung, weil der Zahlungsanbieter selbst keine Hyvä-kompatible Variante anbietet.

<!-- app/code/Vendor/PaymentGateway/view/frontend/templates/iframe.phtml -->
<?php
/** @var \Vendor\PaymentGateway\Block\Iframe $block */
?>
<div class="payment-iframe-wrapper rounded-xl overflow-hidden border border-gray-200">
    <!-- sandbox isolates legacy Luma JS/CSS from the Hyvä page context -->
    <iframe
        src="<?= $block->escapeUrl($block->getIframeUrl()) ?>"
        title="Payment widget"
        sandbox="allow-scripts allow-forms allow-same-origin"
        loading="lazy"
        class="w-full min-h-[420px] border-0"
        referrerpolicy="strict-origin">
    </iframe>
</div>

Wichtig ist die restriktive Auswahl der sandbox-Flags: allow-scripts und allow-forms sind für die meisten Zahlungs-Widgets nötig, allow-same-origin nur, wenn der Anbieter tatsächlich Cookies oder LocalStorage im gleichen Origin-Kontext benötigt. Jedes zusätzliche Flag vergrößert die Angriffsfläche, deshalb sollte man mit der minimalen Kombination starten und nur bei nachgewiesenem Bedarf erweitern.

5. Nicht benötigte Luma-Assets gezielt deaktivieren

Wenn ein Audit zeigt, dass ein Compatibility-Modul zwar technisch existiert, aber keine relevanten Assets ausliefert, lohnt sich die gezielte Deaktivierung statt eines vollständigen Deinstallierens. Zwei Stellhebel sind dafür am wirksamsten: der Ausschluss aus dem RequireJS-Bundle und das Entfernen von Legacy-Blöcken über Layout-XML mit remove="true". Beides verhindert, dass Luma-Assets überhaupt in die ausgelieferten Bundles gelangen, ohne den Code des Drittanbieter-Moduls selbst anzufassen.

Der RequireJS-Ausschluss ist besonders wirksam, weil er verhindert, dass ein einzelnes ungenutztes Luma-Widget das gesamte Bundle aufbläht und zusätzliche HTTP-Requests erzeugt. Layout-XML-Removes wiederum entfernen Blöcke, die zwar registriert, aber für den Hyvä-Checkout gar nicht sichtbar sind, direkt aus dem Rendering-Baum.

<!-- app/design/frontend/Mironsoft/default/requirejs-config.js counterpart in XML form -->
<!-- etc/frontend/di.xml or requirejs-config.js exclusion via bundle config -->
<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">

    <!-- Remove the unused Luma review widget block from the layout tree -->
    <!-- catalog_product_view.xml -->
    <referenceBlock name="product.info.review" remove="true" />

    <!-- Remove legacy Luma CSS reference that is no longer rendered -->
    <referenceContainer name="head.additional">
        <block class="Magento\Framework\View\Element\Template" remove="true"
               name="vendor.reviewmodule.legacy.styles" />
    </referenceContainer>
</config>

Ergänzend gehört in requirejs-config.js ein Eintrag, der das Luma-Widget des Drittanbieter-Moduls explizit aus der Bundle-Erzeugung ausschließt, statt es nur zu ignorieren. So verhindert man zuverlässig, dass ein zukünftiges setup:static-content:deploy das Asset erneut mitzieht, weil ein anderes Compatibility-Modul indirekt darauf verweist.

6. Compatibility-Modul behalten oder direkt portieren?

Nicht jede Situation, in der ein Luma-Rest auftaucht, ruft nach einer vollständigen Portierung nach Hyvä. Ein Compatibility-Modul ist die richtige Wahl, wenn das betroffene Drittanbieter-Modul selten geändert wird, nur an einer klar abgegrenzten Stelle rendert und der Anbieter regelmäßige Updates liefert, die man nicht mit einem eigenen Hyvä-Template synchron halten möchte. Der Wartungsaufwand bleibt beim Hersteller, nicht im eigenen Theme.

Eine direkte Portierung lohnt sich, sobald das Modul zentrale Frontend-Flächen betrifft, häufig angepasst wird oder das Compatibility-Modul spürbar zur Ladezeit beiträgt, etwa durch große RequireJS-Bundles oder blockierendes Luma-CSS. Die vollständige Anleitung zur Portierung von Luma-Modulen nach Hyvä ist ein eigenes Thema; an dieser Stelle zählt nur die Entscheidungslogik: Bleibt der Rest klein, isoliert und selten aktiv, ist das Compatibility-Modul die pragmatischere Wahl. Wächst sein Einfluss auf Performance und Wartung, überwiegt die Portierung.

7. Testing: CSP-Violations erkennen und beheben

Übrig gebliebene Luma-Scripts sind eine häufige Quelle für CSP-Verstöße in Hyvä-Shops, weil sie oft Inline-Handler oder direkt eingebettete <script>-Blöcke enthalten, die Hyvä's Content Security Policy nicht kennt. Der erste Schritt beim Testing ist, die Browser-Konsole und den CSP-Report-Endpunkt systematisch nach Verstößen zu durchsuchen, die von einem konkreten Compatibility-Modul stammen. Erst wenn die Quelle klar zugeordnet ist, lässt sich entscheiden, ob ein registerInlineScript-Aufruf nachgerüstet oder das Skript komplett entfernt werden soll.

Jeder Inline-Script-Block, der aus einem Compatibility-Modul stammt und tatsächlich gebraucht wird, muss über $hyvaCsp->registerInlineScript() registriert werden, damit Hyvä einen passenden Hash oder Nonce in die CSP-Header aufnimmt. Ohne diese Registrierung blockiert der Browser das Skript im enforce-Modus komplett, was in Report-Only-Umgebungen oft unbemerkt bleibt, bis die Policy scharf geschaltet wird.

<?php
/** @var \Hyva\Theme\ViewModel\HyvaCsp $hyvaCsp */
$hyvaCsp = $viewModels->require(\Hyva\Theme\ViewModel\HyvaCsp::class);
?>
<script>
// Inline script required by a legacy Luma fragment (compatibility module)
// Registering it via hyvaCsp avoids CSP violations in enforce mode
document.addEventListener('DOMContentLoaded', function () {
    var legacyWidget = document.querySelector('[data-luma-widget]');
    if (legacyWidget) {
        legacyWidget.dispatchEvent(new CustomEvent('luma:init'));
    }
});
</script>
<?= /* @noEscape */ $hyvaCsp->registerInlineScript() ?>

Zur systematischen Kontrolle empfiehlt sich, die CSP zunächst im Content-Security-Policy-Report-Only-Modus zu betreiben und die eingehenden Reports nach Domains und Skript-Hashes zu filtern, die auf ein bestimmtes Compatibility-Modul zurückführen. So lässt sich vor dem produktiven Umschalten auf enforce jedes betroffene Skript identifizieren und entweder registrieren oder ersatzlos entfernen.

8. Praxisbeispiel: Audit eines Bewertungsmoduls

Ein Drittanbieter-Bewertungsmodul brachte im Rahmen eines Audits ein aktives Compatibility-Modul mit, das seit der ursprünglichen Migration nach Hyvä unverändert lief. Der grep-Audit aus Abschnitt 3 zeigte: Das Modul registrierte zwar einen Layout-Handle für catalog_product_view, der referenzierte Block wurde jedoch bereits durch ein natives Hyvä-Template im Theme überschrieben. Die RequireJS-Datei des Moduls wurde in keinem requirejs-config.js mehr eingebunden.

Das Ergebnis: Das Compatibility-Modul lud pro Produktseite ein 40 KB großes Luma-CSS-Bundle, das nie gerendert wurde, weil der zugehörige Block gar nicht mehr im Seitenbaum stand. Die Entscheidung fiel eindeutig auf Entfernen: Das Compatibility-Modul wurde deaktiviert, der Layout-XML-Eintrag mit remove="true" ergänzt und das ungenutzte RequireJS-Bundle ausgeschlossen. Die Ladezeit der Produktseite sank messbar, ohne dass sich am sichtbaren Bewertungsbereich, der längst über ein natives Hyvä-Template lief, irgendetwas änderte.

9. Vergleichstabelle: behalten vs. entfernen/portieren

Die Entscheidung zwischen aktivem Compatibility-Modul, gezieltem Entfernen des Luma-Rests und vollständiger Portierung nach Hyvä hängt von mehreren Faktoren ab, die sich nicht immer auf den ersten Blick erschließen. Die folgende Tabelle fasst die wichtigsten Abwägungskriterien zusammen.

Kein Wert in dieser Tabelle ist absolut. Ein Compatibility-Modul mit geringem Performance-Impact kann trotzdem ein Wartungsrisiko darstellen, wenn der Drittanbieter seine Luma-Templates unangekündigt ändert. Der Audit aus Abschnitt 3 bleibt deshalb der verlässlichste Ausgangspunkt für jede Einzelfallentscheidung.

10. Zusammenfassung

Compatibility-Module lösen ein reales Problem: Sie erlauben Hyvä-Shops, Drittanbieter-Module ohne native Templates weiter zu betreiben, ohne den gesamten Shop auf Luma zurückzuwerfen. Das Problem entsteht erst, wenn Compatibility-Module ungeprüft aktiv bleiben, obwohl das zugrunde liegende Modul längst keine relevante Frontend-Rolle mehr spielt. Ein gezielter Audit mit grep-Befehlen über Layout-Handles, Blocknamen und RequireJS-Abhängigkeiten zeigt zuverlässig, welche Compatibility-Module echten Nutzen haben und welche nur Ballast sind.

Unvermeidbare Luma-Fragmente, etwa bestimmte Zahlungs-Iframes, lassen sich über sandbox-Attribute sauber isolieren, statt sie ungeschützt in die Hyvä-Seite einzubetten. Nicht benötigte Assets gehören gezielt aus RequireJS-Bundles und dem Layout-Baum entfernt. Und jedes verbleibende Inline-Script muss über registerInlineScript CSP-konform registriert werden, bevor die Policy scharf geschaltet wird. Wer diese vier Schritte konsequent anwendet, hält die Zahl der aktiven Compatibility-Module klein und die Performance des Shops hoch.

11. FAQ: Compatibility-Module in Hyvä-Shops