Child Theme manuell entwickeln

Diese Seite beschreibt den manuellen Workflow für Entwickler:innen, die ein Child-Theme als reguläres Plugin in einem Repo pflegen wollen, ohne den browserbasierten Theme Builder.

• Wann manuell vs. Theme Builder?
• Theme-Skelett mit guppy:theme:create
• Manuelle Erstellung (ohne Generator)
• Plugin installieren und aktivieren
• Theme-Variablen anpassen
• Twig-Overrides
• Iteration
• Plugins installieren
• Verwandt

Wann manuell vs. Theme Builder?

Bedarf	Empfehlung
Brand-Theme mit Variablen-/Asset-Anpassungen	Theme Builder
Eigene Twig-Overrides, Custom-JS, eigene Plugins	manuell
Komplexe Layouts, eigene CMS-Elemente	manuell
Versionskontrolle via Git	manuell (oder Builder + Snapshot ins Repo)
Schnelle Iteration ohne lokales Setup	Theme Builder

Hybridweg

Theme Builder als Starter nutzen, ZIP entpacken, Inhalt ins Repo legen, ab dann manuell weiterentwickeln. Snapshot (.guppy-builder.json) versioniert mitcheckchecken.

Theme-Skelett mit guppy:theme:create

Der schnellste Weg zu einem manuell weiterentwickelbaren Child-Theme:

bin/console guppy:theme:create

Interaktiver Prozess. Eingaben:

• Namespace (z. B. Dmf, Acme)
• Theme-Name (z. B. CustomerShop)
• Theme-Titel für den Admin
• Brand-Farben (Primary, Secondary, Border, Background)
• Asset-Dateinamen (Plugin-Icon, Preview, Logo, Share-Icon, Favicon)

Erzeugte Struktur:

custom/static-plugins/DmfCustomerShopTheme/
├── composer.json
└── src/
    ├── DmfCustomerShopTheme.php
    └── Resources/
        ├── app/storefront/
        │   ├── src/scss/
        │   │   ├── base.scss
        │   │   └── overrides.scss
        │   └── dist/
        │       ├── assets/
        │       └── storefront/js/
        ├── config/plugin.png
        ├── theme.json
        └── views/storefront/

Automatisch erzeugt:

• vollständige composer.json mit Dependency auf dmf/sw6-guppy-theme
• vorkonfigurierte theme.json mit korrekter Vererbung
• PHP-Plugin-Klasse mit korrektem Namespace
• Standard-Assets kopiert

Vererbung in theme.json ist fest verdrahtet:

{
  "configInheritance": [
    "@Storefront",
    "@DmfGuppyTheme"
  ]
}

Assets vorbereiten

Stelle vor dem Befehl Plugin-Icon, Preview-Bild, Logo, Share-Icon und Favicon bereit, der Generator kopiert sie nach Resources/.

Manuelle Erstellung (ohne Generator)

Wenn du den Generator nicht nutzen willst:

custom/plugins/AcmeChildTheme/
├── composer.json
└── src/
    ├── AcmeChildTheme.php
    └── Resources/
        ├── theme.json
        ├── config/plugin.png
        └── app/storefront/src/scss/
            ├── overrides.scss
            └── base.scss

composer.json:

{
  "name": "acme/child-theme",
  "description": "Acme Child Theme",
  "type": "shopware-platform-plugin",
  "license": "proprietary",
  "require": {
    "shopware/core": "~6.7.0",
    "dmf/sw6-guppy-theme": "^2.0"
  },
  "autoload": {
    "psr-4": {
      "AcmeChildTheme\\": "src/"
    }
  },
  "extra": {
    "shopware-plugin-class": "AcmeChildTheme\\AcmeChildTheme",
    "label": {
      "de-DE": "Acme Child Theme",
      "en-GB": "Acme Child Theme"
    }
  }
}

theme.json:

{
  "name": "AcmeChildTheme",
  "author": "Acme",
  "views": ["@Storefront", "@Plugins", "@AcmeChildTheme"],
  "style": [
    "app/storefront/src/scss/overrides.scss",
    "@StorefrontBootstrap",
    "@Plugins",
    "app/storefront/src/scss/base.scss"
  ],
  "script": [
    "@Storefront",
    "@Plugins"
  ],
  "asset": ["@Storefront", "@Plugins", "app/storefront/dist/assets"],
  "configInheritance": ["@Storefront", "@DmfGuppyTheme"],
  "previewMedia": "app/storefront/dist/assets/theme-preview.jpg"
}

Plugin installieren und aktivieren

bin/console plugin:refresh
bin/console plugin:install --activate AcmeChildTheme
bin/console theme:change                           # Sales-Channel auswählen
bin/console theme:compile
bin/console cache:clear

Theme-Variablen anpassen

In overrides.scss (lädt vor Bootstrap):

// abstract/variables/bootstrap.scss-Werte überschreiben
$body-bg: #f00 !default;
$body-color: #000 !default;

// Guppy-spezifische Variablen
$icon-base-size: 16px !default;
$product-image-height: 320px !default;

// Bootstrap-Variablen
$primary: #1A223E !default;
$secondary: #F49927 !default;

In base.scss (lädt nach allem):

// Selektor-Styles
.custom-component {
    background-color: $primary;
    color: $body-color;
}

Reihenfolge zählt

Variablen-Overrides gehören in overrides.scss, in base.scss greifen sie nicht mehr, weil Bootstrap dann bereits kompiliert ist.

Komplette Variablen- und Mixin-Referenz: Variablen & Tokens.

Twig-Overrides

Templates spiegeln den Original-Pfad und nutzen sw_extends:

{# src/Resources/views/storefront/layout/header/header.html.twig #}
{% sw_extends '@Storefront/storefront/layout/header/header.html.twig' %}

{% block layout_header_logo %}
    <div class="header-logo-acme">
        {{ parent() }}
    </div>
{% endblock %}

Detail: Twig-Overrides.

Iteration

Nach jeder Änderung:

bin/console theme:compile
bin/console cache:clear

Bei aktiver Storefront-Watcher-Session reicht Ctrl+S, der Watcher rebuildet automatisch:

bin/watch-storefront.sh

Plugins installieren

DmfGuppyTheme bringt einen Befehl mit, der empfohlene Plugins via Composer holt:

bin/console guppy:install:plugins

Mehr unter Empfohlene Plugins.

Verwandt

• Theme Builder: als Alternative oder Starter.
• Architektur: Vererbungs-Reihenfolge.
• Variablen & Tokens: SCSS-Architektur.
• Twig-Overrides: Template-Override-Patterns.