Workflow

Diese Seite zeigt den empfohlenen End-to-End-Workflow vom ersten Builder-Export bis zur produktiven Storefront, und wie du das Theme iterativ weiterentwickelst.

1. ZIP exportieren

Im Theme Builder Konfiguration füllen, dann Export ZIP. Du erhältst <TechnicalName>.zip.

Snapshot zuerst sichern

Vor dem Export .guppy-builder.json per Save Snapshot herunterladen und versionieren. Ohne Snapshot ist nachträgliches Editieren mühsam, der Builder hat keinen Server-Storage.

2. Plugin installieren

ZIP nach custom/plugins/<technical-name-kebab>/ entpacken (z. B. custom/plugins/AcmeGuppyChildTheme/).

cd /path/to/shopware
unzip ~/Downloads/AcmeGuppyChildTheme.zip -d custom/plugins/

3. Plugin registrieren und aktivieren

bin/console plugin:refresh
bin/console plugin:install --activate AcmeGuppyChildTheme

4. Theme zuweisen

bin/console theme:change

Sales-Channel auswählen, dann Acme Guppy Child Theme wählen.

5. Theme kompilieren

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

Die theme.json-Werte werden jetzt von Shopwares Theme-Compiler in SCSS-Variablen umgesetzt und in das Storefront-CSS gebacken.

6. Smoke-Test

Storefront aufrufen und prüfen:

• Marken-Farben aktiv
• Logo, Favicon, Share-Image korrekt eingebunden
• Eigene Fonts laden (@font-face)
• Layout-Varianten (Header, Footer, Productcards) wie konfiguriert

Iteration: Snapshot-Re-Import

Beim nächsten Anpassungs-Durchlauf:

1. Theme Builder öffnen.
2. Load Snapshot → bestehende .guppy-builder.json laden.
3. Felder ändern (neue Farben, weitere Fonts, weitere Snippets …).
4. Neuen Snapshot speichern (Versionierung).
5. ZIP neu exportieren.
6. Auf der Shopware-Seite Plugin updaten:

unzip -o ~/Downloads/AcmeGuppyChildTheme.zip -d custom/plugins/
bin/console plugin:refresh
bin/console plugin:update AcmeGuppyChildTheme
bin/console theme:compile
bin/console cache:clear

Theme:compile nach jeder Änderung

Reines Plugin-Update reicht nicht, theme:compile muss laufen, damit theme.json-Werte ins kompilierte CSS gebacken werden.

Vererbungs-Reihenfolge (Hintergrund)

Das generierte Plugin folgt diesem Vererbungs-Layout:

overrides.scss (Child)              ← lädt vor @DmfGuppyTheme
   └─ @DmfGuppyTheme                ← Parent-Theme
         └─ base.scss (Child)       ← lädt nach @DmfGuppyTheme

Plus fest verdrahtete theme.json-Inheritance:

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

Diese Struktur ist nicht änderbar, sie sichert, dass das Child immer auf dem Guppy-Default aufsetzt.

Vom Builder ins eigene Repo (optional)

Wer den Builder primär als Starter nutzen will und ab einem bestimmten Punkt manuell weiterentwickelt:

1. ZIP entpacken.
2. Inhalt in dein Plugin-Repo legen, mit git init versionieren.
3. Snapshot (.guppy-builder.json) ebenfalls einchecken, bleibt als Referenz, falls du die Builder-Werte später noch einmal nachladen willst.
4. Ab hier ist der manuelle Workflow zuständig, siehe Child Theme manuell entwickeln.

CI/CD-Hinweise

• ZIP-Generierung läuft client-seitig, sie ist nicht über die Builder-URL automatisierbar.
• Empfohlener CI-Pfad: Plugin-Verzeichnis ins Repo, dort regulär per Composer / Shopware-CLI deployen. Theme-Konfiguration via dmf:theme:export aus DmfCmsImportExport zwischen Stages migrieren.

Troubleshooting

„Plugin nicht gefunden“ nach Upload

bin/console plugin:refresh

Styles greifen nicht

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

Eigene Fonts laden nicht

• Prüfen, ob die .woff2-Dateien tatsächlich in dist/assets/font/ liegen.
• theme:compile und cache:clear ausführen.
• Browser-Cache leeren oder Inkognito-Tab nutzen.

Plugin-Update überschreibt nichts

bin/console plugin:update AcmeGuppyChildTheme

plugin:install würde sich beschweren, wenn das Plugin schon installiert ist, plugin:update ist der korrekte Befehl bei bestehender Installation.