Eigenes Hyvä-Theme von Grund auf erstellen: ohne Compat-Module

1. Einordnung: warum ein eigenes Hyvä-Theme ohne Compat-Module sinnvoll ist

Wer ein eigenes Hyvä-Theme aufsetzt, steht meist vor derselben Entscheidung: das offizielle Hyvä Default Theme (hyva-themes/magento2-default-theme-csp) als Parent nutzen, oder ein Hyvä-Theme von Grund auf auf Basis von Magento/blank bauen. Das Default Theme bringt Kompatibilitätsmodule mit, die Luma-Fallback-Templates für Drittanbietermodule bereitstellen, damit ein Shop auch ohne eigene Anpassung funktioniert. Genau dieser Komfort hat einen Preis: zusätzliche Templates, zusätzliche CSS-Klassen im Tailwind-Build und eine Abhängigkeit, die bei jedem Hyvä-Core-Update mitgepflegt werden muss.

Ein eigenes Hyvä-Theme von Grund auf, das direkt von Magento/blank erbt, verzichtet bewusst auf diesen Ballast. Das Ergebnis ist ein kleineres CSS-Bundle, eine überschaubare Template-Basis und volle Kontrolle über jede Zeile Markup. Die Kehrseite: Fallback-Templates für Module, die keine eigene Hyvä-Kompatibilität mitbringen, entfallen ersatzlos. Wer diesen Weg geht, übernimmt bewusst mehr Eigenverantwortung für Templates, die sonst ein Compat-Modul liefern würde.

Für Agentur-Projekte mit einem klar abgegrenzten Modul-Katalog ist das oft die bessere Wahl, weil sich Performance-Budget und Wartungsaufwand von Anfang an präzise planen lassen, statt ungenutzte Compat-Templates im Bundle mitzuschleppen.

2. Verzeichnisstruktur, registration.php und theme.xml mit Parent Magento/blank

Der erste Schritt für ein eigenes Hyvä-Theme von Grund auf ist die Verzeichnisstruktur unter app/design/frontend/Mironsoft/hyva-custom/. Anders als beim Erben vom Hyvä Default Theme trägt theme.xml hier explizit Magento/blank als Parent, nicht hyva-themes/default. Das ist die zentrale Weiche: Magento löst die Template-Fallback-Kette ab jetzt direkt zu Magento/blank auf, ohne den Umweg über Hyvä-Compat-Templates.

registration.php registriert das Theme in der Magento-Komponentenregistrierung, theme.xml definiert Titel, Vorschaubild und Parent. Beide Dateien sind schlank, entscheidend ist die korrekte Parent-Referenz, weil davon die gesamte spätere Fallback-Auflösung für Templates, Layout-XML und statische Assets abhängt.

<?php
/**
 * Theme registration for the custom Hyva theme.
 * No dependency on hyva-themes/magento2-default-theme-csp.
 */
declare(strict_types=1);

use Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register(
    ComponentRegistrar::THEME,
    'frontend/Mironsoft/hyva-custom',
    __DIR__
);

<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">
    <!-- Parent is Magento/blank, NOT hyva-themes/default -->
    <parent>Magento/blank</parent>
    <title>Mironsoft Hyva Custom</title>
    <media>
        <preview_image>media/preview.jpg</preview_image>
    </media>
</theme>

Nach dem Aktivieren mit bin/magento theme:list zur Kontrolle erscheint das neue Theme in der Liste. Wichtig: Ohne die Hyvä-Compat-Module lösen viele Third-Party-Templates jetzt direkt zu ihren Magento/blank- oder Luma-Vorlagen auf, was in Magento_Theme als ungestylte Darstellung ohne Tailwind-Klassen sichtbar wird, bis die betroffenen Templates im eigenen Theme nachgebaut werden.

3. composer.json: welche Hyvä-Pakete tatsächlich nötig sind

Die composer.json eines eigenen Hyvä-Themes ohne Compat-Module verzichtet bewusst auf hyva-themes/magento2-default-theme-csp. Stattdessen genügen hyva-themes/magento2-tailwind-config für die Tailwind-Basiskonfiguration und optional hyva-themes/magento2-webp-fallback für automatische WebP-Bildauslieferung. Beide Pakete sind reine Tailwind- beziehungsweise Asset-Helfer, keine Compat-Module mit Luma-Fallback-Logik.

Magento/blank kommt über das Core-Framework, nicht als separate Composer-Theme-Abhängigkeit im klassischen Sinn, aber der Parent-Eintrag in theme.xml genügt für die Fallback-Auflösung. Wer zusätzlich Grid- oder Slider-Komponenten von Hyvä nutzen will, bindet diese gezielt einzeln ein, statt ein komplettes Compat-Paket zu importieren, das Dutzende ungenutzte Templates mitbringt.

{
  "name": "mironsoft/theme-frontend-hyva-custom",
  "description": "Custom lean Hyva theme without compat modules, Magento/blank as parent",
  "type": "magento2-theme",
  "license": "OSL-3.0",
  "require": {
    "php": "~8.4.0",
    "hyva-themes/magento2-tailwind-config": "^1.3",
    "hyva-themes/magento2-webp-fallback": "^1.0",
    "hyva-themes/magento2-theme-fallback": ">=1.0.10"
  },
  "autoload": {
    "files": []
  }
}

Der Unterschied wird beim composer why-Baum sichtbar: Ein Hyvä-Theme von Grund auf hat einen deutlich flacheren Abhängigkeitsbaum als ein Theme, das vom Hyvä Default Theme erbt. Weniger Pakete bedeuten weniger Update-Zyklen, aber auch weniger automatisch mitgelieferte Templates.

4. Tailwind-Konfiguration von Grund auf: Content-Pfade richtig setzen

Tailwind CSS v4 scannt in einem eigenen Hyvä-Theme alle .phtml-Dateien nach genutzten Klassen, aber nur dort, wo die content-Pfade in der Konfiguration tatsächlich hinzeigen. Weil ein Hyvä-Theme von Grund auf keine geerbten Hyvä-Default-Templates mitbringt, müssen die Pfade auf das eigene Theme, alle genutzten Magento_-Core-Module unter app/code und relevante Vendor-Module zeigen, sonst fehlen Klassen im finalen CSS-Bundle und Layouts brechen optisch.

Die postcss.config.js bindet den Tailwind-v4-PostCSS-Plugin ein. Wichtig bei einem eigenen Hyvä-Theme: Der Build-Prozess läuft ausschließlich über bin/npm im jeweiligen Tailwind-Verzeichnis des Themes, niemals über einen globalen Tailwind-Aufruf außerhalb des Docker-Containers, weil sonst Pfad- und Versionsinkonsistenzen entstehen.

// tailwind.config.js - content paths for a from-scratch Hyva theme
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    '../../../../**/*.phtml',
    '../../../../../../app/code/**/*.phtml',
    '../../../../../../vendor/hyva-themes/magento2-tailwind-config/**/*.phtml',
    './**/*.phtml'
  ],
  theme: {
    extend: {
      colors: {
        brand: {
          DEFAULT: '#b3294f',
          dark: '#5c1a2e'
        }
      }
    }
  },
  plugins: []
};

// postcss.config.js - Tailwind v4 PostCSS pipeline
module.exports = {
  plugins: {
    '@tailwindcss/postcss': {},
    autoprefixer: {}
  }
};

5. Basis-Templates von Grund auf: default.phtml und Alpine-Bootstrapping

Ohne Hyvä Default Theme als Parent muss default.phtml in Magento_Theme für ein eigenes Hyvä-Theme komplett selbst gebaut werden. Das Grundgerüst enthält das HTML-Skelett, den x-data-Bootstrap für Alpine.js auf <html> oder <body>, sowie die Blöcke für Header, Content und Footer, die über die Iteration von $block->getChildNames() eingebunden werden.

CSP-Konformität ist bei einem Hyvä-Theme von Grund auf Pflicht, nicht optional: Jeder Inline-<script>-Block muss über $hyvaCsp->registerInlineScript() registriert werden, sonst blockiert die Content-Security-Policy den Alpine-Bootstrap im Browser. Da kein Compat-Modul CSP-Handling mitliefert, liegt die vollständige Verantwortung für CSP-konforme Inline-Skripte beim eigenen Theme-Code.

<!-- Magento_Theme/templates/page/default.phtml -->
<?php
/** @var \Magento\Framework\View\Element\Template $block */
/** @var \Hyva\Theme\Model\ViewModelRegistry $viewModels */
/** @var \Hyva\Theme\ViewModel\HyvaCsp $hyvaCsp */
$hyvaCsp = $viewModels->require(\Hyva\Theme\ViewModel\HyvaCsp::class);
?>
<!DOCTYPE html>
<html <?= $block->getChildHtml('html_attributes') ?> x-data="{ mobileMenuOpen: false }">
<head>
    <?= $block->getChildHtml('head.additional') ?>
</head>
<body class="antialiased bg-white text-slate-900" x-data>
<?= $block->getChildHtml('header-content') ?>
<main id="maincontent" class="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8">
    <?= $block->getChildHtml() ?>
</main>
<?= $block->getChildHtml('footer-content') ?>

<script>
    // Bootstrap Alpine store used by header and footer components
    document.addEventListener('alpine:init', () => {
        Alpine.store('mironsoftTheme', { mobileMenuOpen: false });
    });
</script>
<?php $hyvaCsp->registerInlineScript(); ?>
</body>
</html>

6. Minimal-Layout-XML für Header, Footer und Navigation

Header, Footer und Navigation entstehen in einem eigenen Hyvä-Theme über eigene Layout-XML-Dateien in Magento_Theme/layout/default.xml, statt die Blockstruktur des Hyvä-Default-Themes zu erben. Das bedeutet: Container-Namen, Block-Klassen und Template-Pfade werden explizit für das eigene Hyvä-Theme von Grund auf definiert, nicht per remove- oder move-Direktiven aus einem geerbten Layout angepasst.

Diese Direktheit macht das Layout übersichtlicher, weil keine geerbten Blöcke aus dem Default Theme still im Hintergrund mitlaufen. Der Nachteil: jede Layout-Handle-Datei, die das Default Theme sonst mitliefert, etwa für Suchergebnisse, Kundenkonto-Seiten oder Checkout-Steps, muss im eigenen Theme explizit nachgebaut werden, sobald die entsprechende Seite abweichend vom nackten Magento/blank-Rendering aussehen soll.

<!-- Magento_Theme/layout/default.xml -->
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceContainer name="header-content">
            <container name="header.branding" htmlTag="div" htmlClass="flex items-center gap-4 px-4 py-3">
                <block class="Magento\Theme\Block\Html\Header\Logo" name="logo" template="Magento_Theme::html/header/logo.phtml"/>
                <container name="header.navigation" htmlTag="nav" htmlClass="hidden lg:flex gap-6"/>
            </container>
        </referenceContainer>
        <referenceContainer name="footer-content">
            <container name="footer.links" htmlTag="div" htmlClass="grid grid-cols-1 sm:grid-cols-3 gap-6 py-8">
                <block class="Magento\Cms\Block\Block" name="footer.cms.links">
                    <arguments>
                        <argument name="block_id" xsi:type="string">footer-links</argument>
                    </arguments>
                </block>
            </container>
        </referenceContainer>
    </body>
</page>

7. Fallback-Risiken: was jetzt selbst gepflegt werden muss

Der größte Kompromiss bei einem eigenen Hyvä-Theme ohne Compat-Module betrifft die Templates von Magento_Theme, Magento_Catalog und Magento_Checkout. Das Hyvä-Compat-Paket liefert normalerweise angepasste Tailwind-Versionen dieser Templates aus, die ohne Parent-Referenz auf das Hyvä Default Theme schlicht fehlen. Produktlisten, Facettenfilter, Mini-Cart und Checkout-Steps rendern dann im rohen Magento/blank-Markup, bis sie im eigenen Theme nachgebaut sind.

Wer ein Hyvä-Theme von Grund auf plant, sollte vorab eine Inventarliste der genutzten Third-Party-Module erstellen und prüfen, welche davon eigene Hyvä-Templates mitbringen und welche auf ein Compat-Modul angewiesen wären. Für Module ohne native Hyvä-Unterstützung bleibt nur die eigene Nachbildung des Templates, unabhängig von Magento_Catalog oder Magento_Checkout, was den Zeitaufwand am Anfang deutlich erhöht, aber langfristig ein sauberes, vorhersehbares Rendering ohne fremde Fallback-Ketten sichert.

In der Praxis betrifft das vor allem Produktdetailseiten mit Konfigurator-Widgets, Checkout-Schritte mit Zahlungsmodul-Templates und Kundenkonto-Bereiche, die von Drittanbieter-Modulen erweitert werden. Jedes dieser Templates verdient eine bewusste Entscheidung: selbst pflegen, oder das Modul gegen eine Hyvä-native Alternative austauschen.

8. Build- und Deploy-Workflow für ein brandneues Theme

Der erste Deploy eines eigenen Hyvä-Themes folgt einer festen Reihenfolge: zuerst bin/npm install im Tailwind-Verzeichnis des Themes, dann der Tailwind-Build, danach das Leeren von var/view_preprocessed und pub/static/frontend, gefolgt von bin/magento setup:static-content:deploy de_DE -t Mironsoft/hyva-custom -f und abschließend bin/magento cache:flush. Wird diese Reihenfolge vertauscht, landen veraltete oder gar keine CSS-Klassen im deployten Static-Content-Verzeichnis.

Typische Stolperfalle bei einem brandneuen Hyvä-Theme von Grund auf: var/view_preprocessed und pub/static/frontend werden vor dem ersten Deploy nicht gelöscht, wodurch Magento alte, zwischengespeicherte Template-Kompilate ausliefert. Eine weitere häufige Ursache für ein kaputtes Layout ist ein falsch gesetzter content-Pfad in der Tailwind-Konfiguration, der neue Templates schlicht nicht scannt, sowie ein fehlender Fallback-Theme-Eintrag im Backend unter Content > Design > Configuration.

1. bin/npm --prefix app/design/frontend/Mironsoft/hyva-custom/web/tailwind install
2. bin/npm --prefix app/design/frontend/Mironsoft/hyva-custom/web/tailwind run build
3. rm -rf var/view_preprocessed/* pub/static/frontend/*
4. bin/magento setup:static-content:deploy de_DE -t Mironsoft/hyva-custom -f
5. bin/magento cache:flush

9. Vergleichstabelle: eigenes Theme von Grund auf vs. Hyvä Default Theme als Parent

Die Entscheidung zwischen einem eigenen Hyvä-Theme von Grund auf und dem Hyvä Default Theme als Parent hängt von Projektgröße, Teamgröße und langfristiger Wartungsstrategie ab. Beide Wege sind valide, aber mit unterschiedlichen Trade-offs bei Initialaufwand und Update-Sicherheit.

Für kleine bis mittlere Projekte mit überschaubarem Modul-Katalog überwiegt bei einem eigenen Hyvä-Theme häufig der Performance- und Kontrollvorteil. Bei sehr großen Shops mit vielen Drittanbieter-Modulen kann das Hyvä Default Theme als Parent den Initialaufwand deutlich senken, weil dort mehr Fallback-Templates bereits existieren.

10. Zusammenfassung

Ein eigenes Hyvä-Theme von Grund auf mit Magento/blank als Parent liefert volle Kontrolle über Markup, ein schlankeres CSS-Bundle und Unabhängigkeit von Compat-Modul-Updates. registration.php und theme.xml sind schnell aufgesetzt, composer.json bleibt schlank ohne hyva-themes/magento2-default-theme-csp, und Tailwind scannt nur die tatsächlich genutzten Templates.

Der Preis dafür ist Eigenverantwortung: Templates für Magento_Theme, Magento_Catalog und Magento_Checkout, die das Compat-Modul sonst mitliefert, müssen selbst gebaut und gepflegt werden. Wer diesen Trade-off bewusst eingeht und den Build- und Deploy-Workflow sauber einhält, bekommt mit einem Hyvä-Theme von Grund auf ein wartbares, performantes Frontend ohne Luma-Altlasten.

11. FAQ: Eigenes Hyvä-Theme von Grund auf erstellen