Hyvä-Theme für mehrere Stores: Multi-Store-Theme-Strategie

1. Die typische Falle bei Multi-Store-Setups

Sobald ein Magento-Shop mehrere Marken, Länder oder Vertriebskanäle über Websites und Store-Views abbildet, entsteht fast automatisch der Wunsch nach einem eigenen Theme pro Store. Das Logo ist anders, die Farbwelt ist anders, vielleicht unterscheidet sich sogar der Footer-Aufbau. Der naheliegende, aber teure Reflex: das bestehende Hyvä-Theme kopieren, umbenennen und pro Brand getrennt weiterpflegen. Ohne eine bewusste Multi-Store-Theme-Strategie summiert sich das schnell zu drei, vier oder fünf parallelen Codebasen, die bei jedem Hyvä-Core-Update, jedem Sicherheitspatch und jeder Tailwind-Änderung einzeln nachgezogen werden müssen.

Das Problem zeigt sich meist erst Monate später: Ein Bugfix landet im Theme von Brand A, aber nicht in dem von Brand B, weil die Kopien längst auseinandergelaufen sind. Genau hier setzt eine saubere Multi-Store-Theme-Strategie an. Statt das Theme zu duplizieren, wird ein einziges Hyvä-Theme für mehrere Stores betrieben und die Unterschiede zwischen den Stores über Magentos eingebaute Fallback-Hierarchie sowie gezielte ViewModel-Logik abgebildet. Das reduziert die Wartungsfläche auf eine Codebasis, ohne die visuelle und funktionale Differenzierung zwischen den Brands aufzugeben.

2. Magentos Fallback-Hierarchie im Detail

Magento löst Templates, Layout-Dateien, Locale-Dateien und statische Assets über eine feste Fallback-Kette auf: Store-View überschreibt Website, Website überschreibt Default, und Default fällt auf das zugewiesene Theme sowie dessen Parent-Theme zurück. Die Theme-Zuweisung selbst erfolgt im Admin unter Content > Design > Configuration, wo pro Scope-Ebene (Default, Website, Store-View) ein Theme, eine Locale und optionale Design-Änderungen hinterlegt werden. Diese Struktur ist das eigentliche Rückgrat jeder Multi-Store-Theme-Strategie: Ein Store-View muss nichts explizit definieren, das er von seinem übergeordneten Scope erben kann.

In der Praxis bedeutet das: Das Hyvä-Theme wird einmal auf Default-Ebene zugewiesen, alle Websites und Store-Views erben es automatisch. Nur dort, wo tatsächlich ein Unterschied existiert, etwa eine abweichende Locale oder ein spezifischer CMS-Block, wird auf Website- oder Store-View-Ebene ein Override gesetzt. Diese Auflösung greift nicht nur bei Themes, sondern auch bei Layout-Handles, Translation-CSVs und Konfigurationswerten. Wer die Fallback-Hierarchie versteht, erkennt: Ein Hyvä-Theme für mehrere Stores ist kein Kompromiss, sondern der von Magento vorgesehene Regelfall.

<!-- theme.xml - a single Hyva theme shared across all stores/websites -->
<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">
    <title>Mironsoft Multi-Store</title>
    <parent>hyva/default</parent>
    <media>
        <preview_image>media/preview.jpg</preview_image>
    </media>
</theme>

<!-- Conceptual view of the scope resolution stored in core_config_data -->
<!-- Assigned via Admin: Content > Design > Configuration, per scope level -->
<config>
    <default>
        <!-- Fallback theme for every store without an explicit override -->
        <design>
            <theme>
                <theme_id>2</theme_id> <!-- Mironsoft Multi-Store theme -->
            </theme>
        </design>
    </default>
    <websites>
        <brand_a>
            <!-- theme_id inherited from default, only locale is overridden -->
            <general>
                <locale>
                    <code>de_DE</code>
                </locale>
            </general>
        </brand_a>
        <brand_b>
            <general>
                <locale>
                    <code>en_US</code>
                </locale>
            </general>
        </brand_b>
    </websites>
    <stores>
        <brand_a_at>
            <!-- store view override: locale differs, theme stays inherited -->
            <general>
                <locale>
                    <code>de_AT</code>
                </locale>
            </general>
        </brand_a_at>
    </stores>
</config>

3. Ein Theme, viele Brands: CSS Custom Properties statt Theme-Fork

Der visuelle Unterschied zwischen Brands beschränkt sich in den meisten Projekten auf Farben, Radien und Logo-Varianten - selten auf strukturell andere Layouts. Genau dafür eignen sich CSS Custom Properties in Kombination mit Tailwind CSS v4 hervorragend. Statt eines Theme-Forks pro Brand definiert man in einer gemeinsamen CSS-Datei je Store-Code einen eigenen Satz an Custom Properties und schaltet sie über ein Attribut am <html>-Tag um. Das ist der zentrale Baustein einer Multi-Store-Theme-Strategie, die Marken-Individualität ermöglicht, ohne die Template-Logik zu verzweigen.

Das data-store-Attribut wird serverseitig aus dem aktuellen Store-Code gerendert, üblicherweise im Root-Template. Tailwind v4 erlaubt es, diese Custom Properties direkt im CSS-first @theme-Block zu referenzieren, sodass Utility-Klassen wie bg-brand-primary je nach Store automatisch die passende Farbe ziehen. Damit bleibt das Hyvä-Theme für mehrere Stores ein einziges Set an Templates, während sich die Brand-Identität rein über CSS-Variablen und Attribut-Selektoren entfaltet.

/* web/tailwind/theme.css - brand tokens keyed by data-store attribute */
@import "tailwindcss";

/* Default brand tokens, used when no data-store override matches */
:root {
  --color-brand-primary: #0f172a;
  --color-brand-accent: #fb8570;
  --radius-brand-card: 0.75rem;
}

/* Brand A overrides */
[data-store="brand_a_de"],
[data-store="brand_a_at"] {
  --color-brand-primary: #5c1a2e;
  --color-brand-accent: #b3294f;
  --radius-brand-card: 1rem;
}

/* Brand B overrides */
[data-store="brand_b_en"] {
  --color-brand-primary: #1c398e;
  --color-brand-accent: #38bdf8;
  --radius-brand-card: 0.25rem;
}

/* Tailwind v4 CSS-first theme, mapped to the custom properties above */
@theme {
  --color-brand-primary: var(--color-brand-primary);
  --color-brand-accent: var(--color-brand-accent);
}

<!-- Root template renders the current store code into the html tag -->
<html lang="<?= $escaper->escapeHtmlAttr($storeLocale) ?>" data-store="<?= $escaper->escapeHtmlAttr($storeCode) ?>">
<!-- Utility classes like bg-brand-primary resolve per store automatically -->
<body class="bg-white text-brand-primary">

4. ViewModel-basierte Store-Erkennung für bedingtes Rendering

CSS Custom Properties lösen die visuelle Differenzierung, aber manche Unterschiede sind inhaltlich: ein anderer Footer-Text, ein zusätzlicher Trust-Badge, ein store-spezifischer Hinweis zu Zahlungsarten. Für solche Fälle ist ein ViewModel, das StoreManagerInterface injiziert, der sauberste Weg - deutlich robuster als verschachtelte Layout-Handles pro Store, die schnell unübersichtlich werden. Nach den gültigen Coding Standards wird das ViewModel mit Constructor Property Promotion und vollständigem PHPDoc umgesetzt.

Das ViewModel kapselt die Store-Erkennung an einer einzigen Stelle. Templates fragen nur noch isStore('brand_b_en') ab, statt den Store-Code selbst zu ermitteln und zu vergleichen. Das hält die Multi-Store-Theme-Strategie testbar: Die Logik liegt in einer PHP-Klasse, nicht verstreut in mehreren phtml-Dateien, und lässt sich mit PHPUnit gegen unterschiedliche Store-Kontexte prüfen.

<?php

declare(strict_types=1);

namespace Mironsoft\Theme\ViewModel;

use Magento\Framework\Exception\NoSuchEntityException;
use Magento\Framework\View\Element\Block\ArgumentInterface;
use Magento\Store\Model\StoreManagerInterface;

/**
 * ViewModel for store detection used in conditional template rendering
 * without duplicating the Hyva theme per brand.
 */
class StoreContext implements ArgumentInterface
{
    /**
     * @param StoreManagerInterface $storeManager Provides access to the current store scope
     */
    public function __construct(
        private readonly StoreManagerInterface $storeManager
    ) {
    }

    /**
     * Returns the store code of the currently resolved store.
     *
     * @return string
     * @throws NoSuchEntityException
     */
    public function getCurrentStoreCode(): string
    {
        return $this->storeManager->getStore()->getCode();
    }

    /**
     * Checks whether the current store code matches one of the given codes.
     *
     * @param string ...$storeCodes List of store codes to compare against
     * @return bool
     * @throws NoSuchEntityException
     */
    public function isStore(string ...$storeCodes): bool
    {
        return in_array($this->getCurrentStoreCode(), $storeCodes, true);
    }

    /**
     * Returns the CMS block identifier for the footer content of the current store.
     *
     * @return string
     * @throws NoSuchEntityException
     */
    public function getFooterBlockIdentifier(): string
    {
        return 'footer_content_' . $this->getCurrentStoreCode();
    }
}

5. Übersetzungen und i18n je Store-View

Übersetzungen folgen in Magento derselben Fallback-Logik wie Templates. Jede Locale bekommt ein eigenes CSV-Verzeichnis im Theme (i18n/de_DE.csv, i18n/en_US.csv), und wenn ein Store-View eine bestimmte Locale nutzt, sucht Magento zuerst im aktiven Theme, dann im Parent-Theme und schließlich in den Modul-Übersetzungen nach dem passenden Schlüssel. Fehlt eine Übersetzung im spezifischen Theme, greift automatisch die Parent-Theme-CSV - ohne dass eine Zeile Code angepasst werden muss.

Für eine konsistente Multi-Store-Theme-Strategie bedeutet das: Store-spezifische Textabweichungen, etwa ein anderer Markenname im Betreff einer Bestellbestätigung, werden über zusätzliche CSV-Zeilen im gemeinsamen Theme gelöst, nicht über separate Theme-Kopien. Die Locale-Auflösung reiht sich damit exakt in dieselbe Fallback-Kette ein wie Theme-Zuweisung und Layout, was Übersetzungen vorhersehbar und store-übergreifend testbar macht.

6. Layout-Anpassungen pro Store ohne Theme-Duplizierung

Layout-Unterschiede zwischen Stores lassen sich fast immer über ViewModel-Argumente statt über separate Layout-XML-Dateien pro Theme lösen. Ein einzelner Block wird mit dem StoreContext-ViewModel als Argument versehen, und das zugehörige Template entscheidet anhand von isStore(), welcher Inhalt gerendert wird. Das hält die Layout-Struktur für alle Stores identisch und vermeidet, dass sich pro Brand eine eigene, im Detail leicht abweichende Layout-Datei entwickelt, die bei Updates separat gepflegt werden müsste.

Wo tatsächlich store-spezifisches Layout nötig ist, etwa ein zusätzlicher Block nur für einen Store, reicht ein normales <referenceContainer> im bestehenden Layout, gesteuert durch eine Bedingung im ViewModel oder im Block selbst. Diese Herangehensweise bleibt zentraler Bestandteil jeder Multi-Store-Theme-Strategie, weil sie Erweiterungen additiv statt destruktiv behandelt.

<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceContainer name="footer-container">
            <!-- Single block, single theme - content branches via ViewModel, not via theme copies -->
            <block class="Magento\Framework\View\Element\Template"
                   name="footer.brand.content"
                   template="Mironsoft_Theme::footer/brand-content.phtml">
                <arguments>
                    <argument name="store_context" xsi:type="object">Mironsoft\Theme\ViewModel\StoreContext</argument>
                </arguments>
            </block>
        </referenceContainer>
    </body>
</page>

7. Static Content Deployment für mehrere Stores und Locales

Sobald mehrere Store-Views unterschiedliche Locales verwenden, muss setup:static-content:deploy alle relevanten Sprachen in einem Lauf abdecken. Wird eine Locale vergessen, liefert Magento im Produktivbetrieb 404-Fehler für CSS- und JS-Assets dieser Sprache, weil die kompilierten Dateien schlicht fehlen. Die Deploy-Sequenz aus dem gemeinsamen Theme-Setup deckt dabei automatisch alle Stores ab, die auf dasselbe Hyvä-Theme für mehrere Stores zeigen - ein einzelner Deploy-Lauf reicht für alle Brands, solange die Locale-Liste vollständig ist.

Bei sehr großen Katalogen mit vielen Locales lohnt sich eine parallele Ausführung pro Locale, um die Deploy-Zeit zu verkürzen. Wichtig bleibt die Reihenfolge: erst var/view_preprocessed und pub/static leeren, dann deployen, zuletzt den Cache leeren - unabhängig davon, wie viele Stores am gemeinsamen Theme hängen.

#!/usr/bin/env bash
# deploy-multi-store.sh - static content deploy for all store locales
set -euo pipefail

readonly THEME="Mironsoft/default"

# Step 1: always clear preprocessed views and compiled static files first
rm -rf var/view_preprocessed/* pub/static/frontend/*

# Step 2: deploy all locales used across stores/websites in one run
bin/magento setup:static-content:deploy -f \
  de_DE de_AT en_US en_GB \
  -t "$THEME"

# Alternative for large catalogs: parallel deploy per locale
# bin/magento setup:static-content:deploy -f de_DE -t "$THEME" &
# bin/magento setup:static-content:deploy -f en_US -t "$THEME" &
# wait

# Step 3: flush cache once all locales are deployed
bin/magento cache:flush

8. Typische Fallstricke

Der häufigste Fallstrick ist eine falsche Theme-Zuordnung im Admin: Ein Store-View bekommt versehentlich ein explizites Theme zugewiesen, statt die Vererbung vom Default- oder Website-Scope greifen zu lassen. Das durchbricht die Fallback-Kette lokal und führt dazu, dass zukünftige Theme-Updates diesen einen Store nicht mehr erreichen, ohne dass das im Admin sofort auffällt. Ein zweiter Fallstrick ist Cache-Fragmentierung: Wer zu viele ViewModel-Bedingungen in stark frequentierte Blöcke einbaut, erzeugt unnötig viele Full-Page-Cache-Varianten pro Store, was die Cache-Trefferquote spürbar senkt.

Ein dritter, oft übersehener Punkt betrifft store-spezifische robots.txt- und CSP-Einstellungen. Da ein gemeinsames Hyvä-Theme für mehrere Stores keine automatische Trennung dieser Konfigurationswerte erzwingt, werden sie beim Anlegen eines neuen Stores leicht vergessen - mit der Folge, dass ein neuer Store versehentlich die CSP-Regeln oder die Indexierungs-Vorgaben eines anderen Stores erbt, statt eigene Werte zu erhalten.

9. Separates Theme vs. Fallback-Ebenen im Vergleich

Die Entscheidung zwischen Theme-Fork pro Store und einer konsequenten Multi-Store-Theme-Strategie mit Fallback-Ebenen wirkt sich direkt auf Wartungsaufwand, Update-Sicherheit und Time-to-Market neuer Stores aus. Die folgende Tabelle stellt beide Ansätze entlang der wichtigsten Kriterien gegenüber.

In der Praxis zeigt sich: Ein Theme-Fork pro Store fühlt sich am Anfang schneller an, weil keine Fallback-Logik durchdacht werden muss. Sobald jedoch das dritte oder vierte Update ansteht, kehrt sich der vermeintliche Zeitvorteil um. Eine früh etablierte Multi-Store-Theme-Strategie zahlt sich spätestens beim ersten größeren Hyvä-Core-Update aus.

10. Zusammenfassung

Ein Hyvä-Theme für mehrere Stores ist kein Notbehelf, sondern folgt exakt dem Design, das Magento mit seiner Fallback-Hierarchie aus Theme, Website und Store-View vorsieht. Die Theme-Zuweisung im Admin regelt, welcher Scope welches Theme, welche Locale und welche Design-Overrides erbt. CSS Custom Properties übernehmen die visuelle Differenzierung zwischen Brands, ein ViewModel mit StoreManagerInterface übernimmt die inhaltliche. Übersetzungen und Layout-Anpassungen reihen sich in dieselbe Fallback-Logik ein, statt eigene Theme-Zweige zu benötigen.

Der entscheidende Hebel liegt darin, Store-Unterschiede so früh wie möglich additiv statt destruktiv zu modellieren: über Konfiguration, CSS-Variablen und ViewModel-Bedingungen statt über Kopien. Eine konsequente Multi-Store-Theme-Strategie reduziert nicht nur den Wartungsaufwand messbar, sie macht auch jeden neuen Store zu einer Frage der Konfiguration statt einer neuen Entwicklungsaufgabe.

11. FAQ: Multi-Store-Theme-Strategie mit Hyvä