Workflow

This page covers the recommended end-to-end workflow from the first builder export to a production storefront, and how to iterate on the theme.

1. Export the ZIP

In the Theme Builder, fill in the configuration, then Export ZIP. You receive <TechnicalName>.zip.

Save the snapshot first

Before exporting, download .guppy-builder.json via Save Snapshot and version it. Without the snapshot, later edits are painful, the builder has no server-side storage.

2. Install the plugin

Extract the ZIP into custom/plugins/<technical-name-kebab>/ (e.g. custom/plugins/AcmeGuppyChildTheme/).

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

3. Register and activate the plugin

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

4. Assign the theme

bin/console theme:change

Pick the sales channel, then select Acme Guppy Child Theme.

5. Compile the theme

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

Shopware's theme compiler now turns theme.json values into SCSS variables and bakes them into the storefront CSS.

6. Smoke test

Open the storefront and check:

• Brand colors active
• Logo, favicon, share image rendered correctly
• Custom fonts load (@font-face)
• Layout variants (header, footer, product cards) match the configuration

Iteration: snapshot re-import

For each follow-up adjustment:

1. Open the Theme Builder.
2. Load Snapshot → load your existing .guppy-builder.json.
3. Change fields (new colors, more fonts, more snippets…).
4. Save a new snapshot (versioning).
5. Export a fresh ZIP.
6. On the Shopware side, update the plugin:

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 after every change

A plugin update alone isn't enough, theme:compile must run for theme.json values to land in the compiled CSS.

Inheritance order (background)

The generated plugin follows this inheritance layout:

overrides.scss (child)              ← loads before @DmfGuppyTheme
   └─ @DmfGuppyTheme                ← parent theme
         └─ base.scss (child)       ← loads after @DmfGuppyTheme

Plus fixed theme.json inheritance:

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

This structure is not changeable, it guarantees the child always sits on top of the Guppy default.

From builder to your own repo (optional)

If you use the builder as a starter and want to continue manually from a certain point:

1. Extract the ZIP.
2. Move the contents into your plugin repo, version with git init.
3. Check in the snapshot (.guppy-builder.json) too, keeps the builder values reloadable.
4. From here on the manual workflow takes over, see Manual Child Theme Development.

CI/CD notes

• ZIP generation runs client-side, there is no automation hook through the builder URL.
• Recommended CI path: keep the plugin folder in your repo and deploy via standard Composer / Shopware CLI. Migrate theme configuration between stages via dmf:theme:export from DmfCmsImportExport.

Troubleshooting

"Plugin not found" after upload

bin/console plugin:refresh

Styles don't apply

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

Custom fonts don't load

• Verify the .woff2 files actually live in dist/assets/font/.
• Run theme:compile and cache:clear.
• Clear the browser cache or use an incognito tab.

Plugin update doesn't override anything

bin/console plugin:update AcmeGuppyChildTheme

plugin:install complains if the plugin is already installed, plugin:update is the correct command for an existing installation.