Ein Hyvä-Child-Theme richtig aufbauen

Fast jeder Hyvä-Shop beginnt mit derselben Entscheidung: das Standard-Theme direkt ändern oder ein Child-Theme darauf aufbauen. Die Antwort lautet immer: Child-Theme. Wie Sie es aufbauen, entscheidet darüber, ob Hyvä-Updates einen Nachmittag oder eine Woche dauern.

Dieser Leitfaden erklärt, wie wir Hyvä-Child-Themes für Kundenshops und für unseren eigenen Demo-Shop einrichten. Er behandelt die benötigten Dateien, was Sie überschreiben und was Sie unangetastet lassen sollten, und die Fehler, die wir am häufigsten in Shops sehen, die zu uns kommen für ein Hyvä-Projekt.

Warum ein Child-Theme und keine Kopie

Hyvä liefert sein Standard-Theme als Composer-Paket aus. Wenn Hyvä einen Fix oder eine Verbesserung veröffentlicht, aktualisiert Composer dieses Paket im vendor-Ordner.

Wenn Sie diese Dateien direkt bearbeiten, gehen Ihre Änderungen beim nächsten Update verloren. Wenn Sie das gesamte Theme in einen eigenen Ordner kopieren, behalten Sie Ihre Änderungen, verlieren aber jede künftige Verbesserung, weil nichts mehr vom Original erbt.

Ein Child-Theme liegt dazwischen. Der Theme-Fallback von Magento sucht zuerst in Ihrem Theme und greift für alles, was Sie nicht überschrieben haben, auf das Parent-Theme zurück. Ihre Abweichungen gehören Ihnen, um den Rest kümmert sich weiterhin Hyvä.

• Updates des Parent-Themes erreichen Ihren Shop automatisch.
• Ihr Diff bleibt klein, sodass sich ein Update schnell prüfen lässt.
• Entwickler sehen auf einen Blick, was individuell und was Standard ist.

Die minimalen Dateien

Ein Hyvä-Child-Theme ist ein ganz normales Magento-2-Theme. Es liegt unter app/design/frontend/Vendor/theme und benötigt zur Registrierung zwei kleine Dateien.

Die erste ist theme.xml, die das Parent-Theme festlegt:

<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">
    <title>Vendor Default</title>
    <parent>Hyva/default</parent>
</theme>

Die zweite ist registration.php:

<?php
use Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register(
    ComponentRegistrar::THEME,
    'frontend/Vendor/default',
    __DIR__
);

Als Nächstes folgt web/tailwind Ordner. Laut Hyvä-Dokumentation kopieren Sie ihn aus dem Parent-Theme, weil jedes Theme sein eigenes Stylesheet baut. Dieser Ordner enthält die Tailwind-Konfiguration, das Quell-CSS und die package.json mit den Build-Skripten.

Danach ausführen: bin/magento setup:upgrade, anschließend weisen Sie das Theme unter Content > Design > Configuration Ihrer Store View zu und bauen das CSS einmal. Damit haben Sie ein funktionierendes Child-Theme, das genau wie Hyvä default aussieht.

So wenig wie möglich überschreiben

Das häufigste Problem, das wir sehen, ist ein Child-Theme, das die Hälfte des Parent-Themes enthält. Jemand musste eine Zeile im Header ändern und hat dafür den gesamten Magento_Theme Template-Ordner kopiert. Zwei Jahre später weiß niemand mehr, welche dieser Dateien tatsächlich geändert wurden.

Unsere Regel ist einfach: ein überschriebenes Template bedeutet eine kopierte Datei. Bevor wir ein Template kopieren, prüfen wir, ob eine kleinere Änderung genügt.

1. Zuerst Layout-XML. Blöcke verschieben, entfernen oder hinzufügen ist eine Layout-Änderung, keine Template-Änderung. Eine default.xml oder eine seitenspezifische Layout-Datei in Ihrem Theme erledigt das meiste davon, ohne eine einzige .phtml Datei anzufassen.
2. Dann Tailwind-Klassen. Viele optische Änderungen sind nur andere Farben, Abstände oder Schriften. Diese gehören in die Tailwind-Konfiguration, nicht in kopierte Templates.
3. Zuletzt das Template-Override. Wenn sich das Markup selbst ändern muss, kopieren Sie genau dieses eine Template in denselben Pfad in Ihrem Theme und ändern es dort.

Wenn wir ein Template kopieren, setzen wir oben einen kurzen Kommentar, was geändert wurde und warum. Das kostet zehn Sekunden und erspart beim nächsten Update viel Rätselraten.

Tailwind weiterhin auf das Parent-Theme schauen lassen

Tailwind erzeugt nur CSS für Klassen, die es in Ihren Quelldateien findet. Deshalb sind Hyvä-Stylesheets klein: Ungenutzte Utilities landen nie im Build.

Die Kehrseite: Tailwind muss jedes Template scannen, das Ihr Shop rendert. Dazu gehören die Templates in Ihrem Child-Theme und die Templates, die weiterhin aus dem Parent-Theme im vendor-Ordner ausgeliefert werden. Die von Hyvä kopierte Tailwind-Konfiguration zeigt bereits auf das Parent-Theme, und diesen Pfad sollten Sie beim Bearbeiten beibehalten.

Hyvä-kompatible Module können außerdem eigene Templates und Tailwind-Quellen mitbringen. Hyvä stellt dafür einen Befehl bereit, bin/magento hyva:config:generate, der eine Liste dieser Modulpfade schreibt, die der Build übernimmt. Führen Sie ihn immer aus, wenn Sie ein Hyvä-kompatibles Modul hinzufügen oder entfernen.

Wenn eine Klasse in der Entwicklung funktioniert, in Produktion aber verschwindet, ist meist ein fehlender Content-Pfad die Ursache. Den vollständigen Build erklären wir in unserem Beitrag über Tailwind-Design-Tokens und die Build-Pipeline.

Übersetzungen, Assets und Theme-Einstellungen

Einige weitere Dinge gehören ins Child-Theme und werden leicht vergessen.

• Übersetzungen. Strings auf Theme-Ebene gehören in i18n/de_DE.csv und ähnliche Dateien in Ihrem Theme. Store-View-spezifische Formulierungen waren einer der Stolpersteine in unserem mehrsprachigen Demo-Shop – testen Sie daher jede Store View, nicht nur die Standardansicht.
• Bilder und Schriften. Theme-Bilder wie die Kacheln auf der Startseite gehören in den web Ordner. In unserem Demo-Shop sind sie im WebP-Format, 720 Pixel breit und mit einer Qualität von etwa 72 komprimiert.
• Farben, die Ihr Team ändern möchte. Wir stellen Header- und Markenfarben unter Stores > Configuration bereit, sodass ein Marketingteam sie ohne Entwickler ändern kann. Die Tailwind-Tokens werden beim Deployment aus Konfiguration und Theme-Dateien neu gebaut.

Zu Schriften ein kurzer Hinweis: Eine einzige selbst gehostete Schriftfamilie mit wenigen Schnitten ist meist leichter, als mehrere über einen Drittanbieter-Dienst zu laden.

CSS bei jedem Deployment bauen

Das kompilierte Stylesheet ist ein Build-Artefakt. Es sollte beim Deployment erzeugt werden – nicht von Hand bearbeitet und nicht committet, nachdem jemand einen Build auf dem Laptop ausgeführt hat.

Ein typischer Deployment-Schritt sieht so aus:

bin/magento hyva:config:generate
npm --prefix app/design/frontend/Vendor/default/web/tailwind ci
npm --prefix app/design/frontend/Vendor/default/web/tailwind run build-prod
bin/magento setup:static-content:deploy -f en_GB de_DE

Der genaue Name des Build-Skripts hängt von Ihrer Hyvä-Version ab; prüfen Sie daher die package.json in Ihrem Theme. In unserem eigenen Stack betreiben wir Magento im Production-Modus mit Static Content Deploy, daher läuft der CSS-Build immer, bevor die statischen Inhalte erzeugt werden.

Häufige Fehler, die wir beheben

Diese Probleme begegnen uns am häufigsten, wenn wir einen bestehenden Hyvä-Shop prüfen.

Die dritte Zeile ist für die Geschwindigkeit am wichtigsten. Eine einzige alte Extension, die ihr Luma-JavaScript lädt, kann einen Großteil dessen zunichtemachen, was Hyvä gewinnt – weshalb wir jede Extension vor einer Migration prüfen.

FAQ

Kann ich mehr als ein Child-Theme haben?

Ja. Magento unterstützt Theme-Ketten, Sie können also ein Basis-Child-Theme für gemeinsame Anpassungen haben und darauf ein weiteres Theme pro Marke oder Store View. Halten Sie die Kette kurz, denn jede Ebene erschwert das Debugging ein wenig.

Sollte ich mit Hyvä default oder mit Hyvä UI beginnen?

Hyvä default ist immer das Parent-Theme. Hyvä UI ist eine Bibliothek fertiger Komponenten, die Sie bei Bedarf in Ihr Theme kopieren. Beide Wege führen zum selben Ergebnis: einem Child-Theme von Hyva/default mit Ihren eigenen Templates.

Brauche ich ein Child-Theme, wenn ich nur Farben ändere?

Ja. Auch kleine Änderungen brauchen einen Ort, der Updates übersteht. Ein Child-Theme mit nur einer Tailwind-Konfiguration und ohne Templates ist völlig in Ordnung – und am einfachsten zu warten.

Sie möchten ein Hyvä-Theme, das leicht aktualisierbar bleibt? Wie wir arbeiten, sehen Sie auf unserer Seite zur Hyvä-Theme-Entwicklung, oder kontaktieren Sie uns , um über Ihren Shop zu sprechen.