Shopware 6 Childtheme

Q: Kann der Betreiber Farben selbst ändern?

Ja – über config-Felder in der theme.json erscheinen Farb-/Logo-Felder im Theme-Manager, ohne Code.

Lesezeit: 6 Min · getestet auf Shopware 6.7.x

Kurzdefinition: Ein Childtheme ist ein eigenständiges Theme-Plugin, das vom Standard-Theme von Shopware 6 (@Storefront) erbt und es gezielt überschreibt – ohne den Core oder das Eltern-Theme zu verändern. So bleiben alle Anpassungen updatesicher.

Auf einen Blick

Was: vererbendes Theme für eigene Storefront-Anpassungen
Für wen: Shop-Betreiber (Beauftragung) und Entwickler (Umsetzung)
Kernnutzen: Anpassungen überstehen jedes Shopware-Update
Technisch: ein Plugin mit theme.json, das @Storefront erbt
Anti-Pattern: direkt im Standard-Theme ändern – wird bei Updates überschrieben

1. Was ist ein Childtheme? — Händler-Sicht

Wenn Sie Ihren Shopware-Shop optisch anpassen lassen – Farben, Logo, Schriften, Layout – gibt es zwei Wege: die Änderung direkt im mitgelieferten Standard-Theme oder in einem Childtheme. Der Unterschied entscheidet über Geld und Nerven.

Wird direkt am Standard-Theme geändert, sind diese Anpassungen beim nächsten Shopware-Update potenziell weg – überschrieben vom Core-Update. Ein Childtheme dagegen liegt neben dem Standard, erbt dessen komplettes Aussehen und überschreibt nur die gewünschten Stellen. Updates des Eltern-Themes laufen weiter durch, Ihre Anpassungen bleiben.

Im Admin sehen Sie das Theme unter Inhalte › Themes. Hier wird das Childtheme dem jeweiligen Verkaufskanal zugewiesen, im Theme-Manager konfiguriert (Farben, Logo, Schriften ohne Code) und kompiliert.

Faustregel für Betreiber: Jede individuelle Gestaltung gehört in ein Childtheme. Wenn Ihnen jemand anbietet, „schnell mal direkt im Theme“ etwas zu ändern – fragen Sie nach dem Childtheme. Alles andere ist technische Schuld, die beim nächsten Update fällig wird.

2. Wofür braucht man es konkret?

Typische Fälle, in denen ein Childtheme der richtige Ort ist:

Corporate Identity: eigenes Logo, Markenfarben, Hausschrift
Layout-Feinschliff: Abstände, Header-/Footer-Anpassungen, Produktkachel-Design
Eigene SCSS-/CSS-Regeln und zusätzliches JavaScript fürs Frontend
Template-Overrides einzelner Twig-Blöcke – etwa Flyout-Menü, Produktdetailseite, Footer
Theme-Konfiguration: eigene Felder im Theme-Manager (z. B. eine wählbare Akzentfarbe)

Nicht ins Childtheme gehören Geschäftslogik oder Datenmodelle – das ist Sache eines Plugins, nicht des Themes. Die Grenze ist einfach: Theme = Aussehen, Plugin = Funktion.

3. Childtheme anlegen — Schritt für Schritt (Entwickler)

Seit Shopware 6 sind Themes technisch Plugins mit einer theme.json und einer Plugin-Klasse, die ThemeInterface implementiert. Der schnellste Start ist der Generator:

bin/console theme:create SwagChildTheme

Das Grundgerüst sieht dann so aus:

custom/plugins/SwagChildTheme/
├── composer.json
└── src/
    ├── SwagChildTheme.php            // Plugin-Klasse, implements ThemeInterface
    └── Resources/
        ├── theme.json                // Herzstück: Vererbung + Konfiguration
        ├── app/storefront/src/
        │   ├── main.js               // eigenes JavaScript
        │   └── scss/
        │       ├── base.scss         // eigene Styles / Variablen-Overrides
        │       └── overrides.scss
        └── views/storefront/         // Twig-Overrides via sw_extends

Die composer.json deklariert das Plugin als shopware-platform-plugin und registriert den Namespace per PSR-4. Die Plugin-Klasse bleibt schlank – sie implementiert lediglich Shopware\Storefront\Theme\ThemeInterface (im Childtheme oft komplett leer, weil die ganze Logik in der theme.json steckt).

4. Die theme.json im Detail

Die theme.json ist das Herzstück. Die Reihenfolge in style, script und views ist die Vererbungskette: @Storefront zuerst (erbt alles vom Standard), danach die eigene Datei (überschreibt):

{
  "name": "SwagChildTheme",
  "author": "great2gether",
  "views": [ "@Storefront", "@Plugins", "@SwagChildTheme" ],
  "style": [
    "@Storefront",
    "app/storefront/src/scss/base.scss"
  ],
  "script": [
    "@Storefront",
    "app/storefront/src/main.js"
  ],
  "asset": [ "app/storefront/src/assets" ]
}

views – Reihenfolge der Template-Vererbung. @Storefront zuerst, eigenes Theme zuletzt.
style / script – SCSS- bzw. JS-Vererbung, gleiche Logik.
asset – statische Dateien (Bilder, Fonts), die mit ausgeliefert werden.
config (optional) – definiert Felder für den Theme-Manager: Farb-, Text- oder Media-Felder in Tabs und Blöcken. So kann der Betreiber Logo und Farben ohne Code im Admin ändern.

Wichtig: Genau dieses @Storefront-zuerst-Prinzip macht das Theme updatesicher. Du erbst alles und überschreibst nur, was nach deiner Datei kommt.

5. SCSS-Overrides

Shopware liefert seine Storefront-Styles als SCSS samt Variablen. Im Childtheme überschreibst du gezielt – am saubersten über die vorhandenen Variablen, nicht mit Brachialgewalt:

// app/storefront/src/scss/base.scss
$sw-color-brand-primary: #b34a00;
$font-family-base: "Inter", sans-serif;

.header-logo img { max-height: 48px; }

Vermeide !important – arbeite stattdessen über die Vererbungs- und Spezifitätsreihenfolge. Da deine SCSS-Datei nach @Storefront geladen wird, gewinnt sie ohnehin bei gleicher Spezifität.

6. Twig-Overrides mit sw_extends

Template-Anpassungen laufen über sw_extends. Du kopierst nicht das ganze Template, sondern erweiterst nur den Block, den du brauchst – Pfad und Dateiname müssen dem Original entsprechen:

{% sw_extends '@Storefront/storefront/layout/header/header.html.twig' %}

{% block layout_header_logo %}
    {# eigenes Logo-Markup #}
    {{ parent() }}
{% endblock %}

Die Block-Namen findest du in den Originalen unter vendor/shopware/storefront/Resources/views/storefront/. Lege deine Datei unter demselben relativen Pfad in views/storefront/ ab, dann greift der Override automatisch.

7. JavaScript ins Theme einbinden

Eigenes Frontend-JavaScript registrierst du als Storefront-Plugin in der main.js und baust die Storefront neu:

// app/storefront/src/main.js
import MyPlugin from './plugin/my-plugin/my-plugin.plugin';

const registry = window.PluginManager;
registry.register('MyPlugin', MyPlugin, '[data-my-plugin]');

Danach Storefront kompilieren (siehe nächster Abschnitt). Inline-Scripts im Twig sind tabu – alles gehört ins gebündelte Asset.

8. Aktivieren, zuweisen, kompilieren — die CLI-Befehle

Die Reihenfolge ist entscheidend, sonst „passiert sichtbar nichts“:

bin/console plugin:refresh
bin/console plugin:install --activate SwagChildTheme
bin/console theme:change            # Childtheme dem Sales Channel zuweisen
bin/console theme:compile
bin/console cache:clear

Nach SCSS-Änderungen reicht theme:compile; nach Twig- oder Config-Änderungen zusätzlich cache:clear. Für JS-Änderungen die Storefront neu bauen (bin/build-storefront.sh bzw. der Watcher im Dev-Setup).

9. Aus der Praxis — was die Docs verschweigen

Hier wird es „zwei Etagen tiefer“. Die offizielle Doku erklärt das Anlegen. Was sie nicht erzählt:

parent() ist in 6.7 in bestimmten Bulk-Edit-Overrides unzuverlässig und kann die Admin-Maske komplett crashen. Workaround: in dem Fall den Core-Block-Inhalt kopieren statt parent() zu rufen.
theme:compile ist nicht dasselbe wie Cache leeren. Wer nur eines macht, sieht „nichts passiert“ und sucht am falschen Ende.
Childtheme aktiv ≠ zugewiesen. Das Plugin ist aktiv, aber das Theme nie dem Sales Channel zugewiesen → es passiert sichtbar gar nichts. Immer theme:change bzw. die Admin-Zuweisung gegenprüfen.
Assets landen nicht im Frontend, wenn der asset-Pfad in der theme.json fehlt – ein stiller Fehler ohne Fehlermeldung.
Anti-Pattern !important: SCSS zukleistern statt über Spezifität/Vererbung zu arbeiten. Funktioniert kurzfristig, wird langfristig unwartbar.
Theme-Cache nach Deploy: Auf Produktion nach jedem Theme-Deploy theme:compile + HTTP-Cache invalidieren, sonst sehen Besucher veraltete Styles.

10. Childtheme vs. eigenes Theme vs. App

Childtheme (erbt @Storefront): der Standardfall für 95 % aller Projekte.
Eigenständiges Theme (erbt nichts): nur sinnvoll, wenn man wirklich bei null anfangen will – selten.
App statt Plugin: für Shopware-Cloud/SaaS, wo kein Server-Zugriff besteht. Themes sind auch als App möglich, mit Einschränkungen.

Häufige Fragen

Überlebt mein Childtheme ein Shopware-Update? Ja – solange du nur überschreibst und nicht den Core/das Eltern-Theme direkt änderst. Genau dafür existiert es.

Childtheme oder eigenes Theme von Grund auf? Für 95 % der Fälle das Childtheme. Ein komplett eigenständiges Theme nur, wenn du nichts vom Standard erben willst.

Brauche ich für jede Kleinigkeit ein Childtheme? Sobald du eine zweite Anpassung machst: ja. Spätestens dann zahlt sich die Struktur aus.

Kann der Betreiber Farben selbst ändern? Ja – über config-Felder in der theme.json erscheinen Farb-/Logo-Felder im Theme-Manager, ohne Code.

Warum sehe ich meine Änderung nicht? Fast immer eine der drei Ursachen: nicht kompiliert, nicht zugewiesen, oder Cache nicht geleert.