WebP-Konvertierung im Hyvä-Build-Prozess automatisieren

1. Warum WebP-Konvertierung im Hyvä-Shop Performance-Vorteile bringt

WebP ist ein von Google entwickeltes Bildformat, das sowohl verlustbehaftete als auch verlustfreie Kompression sowie Alphatransparenz unterstützt und damit sowohl JPEG als auch PNG ersetzen kann. Bei vergleichbarer visueller Qualität, gemessen etwa über SSIM, liegt die Dateigröße nach einer WebP-Konvertierung typischerweise 25 bis 35 Prozent unter dem JPEG- oder PNG-Original. Ein 1200x1200 Pixel großes Produktbild mit 180 KB als JPEG landet nach der Konvertierung meist bei 110 bis 130 KB, ohne dass Kunden den Unterschied im Produktbild erkennen.

In einem Hyvä-Shop mit 24 bis 48 Produktbildern pro Kategorieseite summiert sich dieser Effekt schnell zu mehreren Megabyte eingesparter Übertragung pro Seitenaufruf. Gerade mobile Besucher in schwachen Netzen profitieren unmittelbar von kleineren Payloads. Da WebP-Bildformate direkt in die Core-Web-Vitals-Bewertung von Google einfließen, ist eine automatisierte WebP-Konvertierung eine der Optimierungen mit dem besten Verhältnis von Aufwand zu messbarem Performance-Gewinn.

2. Magentos natives Bild-Resizing und seine Grenzen

Magento generiert beim Katalog-Import und beim Speichern von CMS-Inhalten automatisch mehrere Bildgrößen (Thumbnail, Small Image, Base Image, Swatch) und legt sie unter pub/media/catalog/product/cache/<hash>/ ab. Dieses native Resizing kümmert sich um Skalierung und Zuschnitt, aber nicht um das Ausgabeformat: Ein hochgeladenes JPEG bleibt ein JPEG, ein PNG bleibt ein PNG, unabhängig davon, wie viele Größenvarianten erzeugt werden.

Für eine WebP-Konvertierung reicht die native Magento-Pipeline also nicht aus. Auch der Media-Gallery-Import über bin/magento catalog:images:resize erzeugt ausschließlich Varianten im Ursprungsformat. Wer WebP-Bildformate im Hyvä-Theme nutzen will, muss diesen Schritt als eigenständige Pipeline-Stufe ergänzen, entweder direkt nach dem Import oder als Teil des Deployments, damit für jede vorhandene Bildvariante zusätzlich eine WebP-Datei mit identischem Basisnamen entsteht.

3. Das picture-Element mit source type=image/webp und Fallback

Damit Browser, die kein WebP unterstützen, sowie Crawler und Bots weiterhin ein funktionierendes Bild erhalten, wird die WebP-Konvertierung im Frontend nie ohne Fallback ausgeliefert. Das picture-Element mit einem source-Tag für image/webp und einem klassischen img-Fallback ist dafür das etablierte Muster: Der Browser wählt automatisch die erste passende Quelle, ohne dass JavaScript beteiligt ist.

In einem Hyvä-Template ersetzt dieses Muster den einfachen img-Tag für Produktbilder in Listing und Detailansicht. Wichtig ist, dass Breite, Höhe und loading-Attribut weiterhin am img-Tag gesetzt werden, da source-Elemente selbst keine Layout-Dimensionen an den Browser melden und CLS sonst unnötig steigen kann.

{{-- product/list/item/image.phtml - picture element with WebP source and fallback --}}
<picture>
    <source
        srcset="{{ $block->getWebpImageUrl($image) }}"
        type="image/webp">
    <img
        src="{{ $image->getUrl() }}"
        srcset="{{ $image->getUrl() }} 1x, {{ $image->getUrl2x() }} 2x"
        width="{{ $image->getWidth() }}"
        height="{{ $image->getHeight() }}"
        loading="lazy"
        decoding="async"
        alt="{{ $block->escapeHtmlAttr($image->getLabel()) }}"
        class="object-cover w-full h-full">
</picture>

4. Ein Build-Schritt mit sharp oder cwebp für die Batch-Konvertierung

Für die eigentliche WebP-Konvertierung eignen sich zwei Werkzeuge: das CLI-Tool cwebp aus der libwebp-Distribution, direkt im Deploy-Container per apt-get install webp verfügbar, oder die Node-Bibliothek sharp, die sich in ein bestehendes Node-Build-Skript einhängen lässt. cwebp ist ideal für einfache Bash-Batchläufe, sharp punktet, wenn ohnehin ein Node-Toolchain für Tailwind oder Alpine-Assets läuft.

Beide Varianten sollten Qualität 80 bis 82 als Ausgangswert verwenden, denn darüber ist der Dateigrößenvorteil kaum noch messbar, darunter werden Artefakte in Produktfotos mit feinen Texturen sichtbar. Ein Batch-Lauf über pub/media/catalog/product iteriert rekursiv über alle JPEG- und PNG-Dateien und legt jeweils eine .webp-Datei mit identischem Namen daneben, ohne das Original zu verändern oder zu löschen.

#!/usr/bin/env bash
# webp-convert.sh - batch WebP conversion for catalog and CMS images
set -euo pipefail

readonly MEDIA_DIR="pub/media/catalog/product"
readonly QUALITY=82
readonly LOG_FILE="var/log/webp-convert.log"

convert_image() {
  local src="$1"
  local dest="${src%.*}.webp"

  # Skip if a fresh WebP variant already exists
  if [[ -f "$dest" && "$dest" -nt "$src" ]]; then
    return 0
  fi

  if cwebp -quiet -q "$QUALITY" "$src" -o "$dest" 2>>"$LOG_FILE"; then
    echo "[OK] $src -> $dest"
  else
    echo "[SKIP] conversion failed, keeping original: $src" | tee -a "$LOG_FILE"
    rm -f "$dest"
  fi
}

find "$MEDIA_DIR" -type f \( -iname "*.jpg" -o -iname "*.jpeg" -o -iname "*.png" \) -print0 |
  while IFS= read -r -d '' file; do
    convert_image "$file"
  done

echo "WebP conversion finished for $MEDIA_DIR"

Wer die Node-Variante bevorzugt, kapselt die WebP-Konvertierung als eigenes npm-Skript neben dem Tailwind-Build. Die Bibliothek sharp nutzt libvips intern und ist für große Bildmengen deutlich schneller als sequenzielle cwebp-Aufrufe, weil sie mehrere Bilder parallel über einen Worker-Pool verarbeitet.

{
  "name": "hyva-image-pipeline",
  "private": true,
  "scripts": {
    "images:webp": "node scripts/convert-webp.js pub/media/catalog/product"
  },
  "dependencies": {
    "sharp": "^0.33.0"
  }
}

5. Integration der WebP-Konvertierung in die Deploy-Sequenz

Damit die WebP-Konvertierung nicht als vergessener manueller Schritt endet, gehört sie fest in die bestehende Deploy-Sequenz des Mark-Shust-Docker-Setups. Der richtige Zeitpunkt liegt nach setup:static-content:deploy, weil dort erst die finalen Theme-Assets und Bildgrößen in pub/static und pub/media vorliegen, und vor cache:flush, damit der Full-Page-Cache erst nach vollständiger Konvertierung wieder befüllt wird.

In der Praxis reicht ein zusätzlicher Aufruf des Konvertierungsskripts als eigener Schritt im Deploy-Runbook oder in der CI-Pipeline. Da cwebp bereits vorhandene, aktuelle WebP-Dateien überspringt, bleibt ein wiederholter Deploy-Lauf schnell, weil nur neu hinzugekommene oder geänderte Bilder tatsächlich konvertiert werden.

#!/usr/bin/env bash
# deploy.sh - deploy sequence extended with WebP conversion step
set -euo pipefail

echo "1/5: rebuilding Tailwind CSS"
bin/npm --prefix app/design/frontend/Mironsoft/default/web/tailwind run build

echo "2/5: clearing static file caches"
cd src && rm -rf var/view_preprocessed/* pub/static/frontend/* && cd -

echo "3/5: deploying static content"
bin/magento setup:static-content:deploy de_DE en_US -t Mironsoft/default -f

echo "4/5: converting catalog and CMS images to WebP"
bin/cli bash bin/webp-convert.sh

echo "5/5: flushing cache"
bin/magento cache:flush

echo "Deploy finished, WebP conversion completed before cache flush"

6. Lazy Loading und Core Web Vitals im Zusammenspiel mit WebP

WebP-Konvertierung und Lazy Loading lösen unterschiedliche Probleme, ergänzen sich aber in der Wirkung auf Core Web Vitals. Kleinere WebP-Dateien reduzieren die reine Übertragungszeit, loading="lazy" verhindert, dass Bilder außerhalb des sichtbaren Bereichs überhaupt angefragt werden. Für das Largest Contentful Paint Element, meist das erste Produktbild oder Hero-Bild, sollte loading jedoch bewusst weggelassen oder auf eager gesetzt werden, damit der Browser es sofort priorisiert lädt.

Für Cumulative Layout Shift sind explizite width- und height-Attribute am img-Tag entscheidend, unabhängig vom Bildformat. Da das picture-Element die Dimensionen vom eingebetteten img-Tag übernimmt, bleibt das Seitenlayout stabil, selbst wenn die WebP-Variante geringfügig andere Kompressionsartefakte als das Original zeigt. Die Kombination aus WebP-Bildformaten, korrekten Dimensionsattributen und gezieltem Lazy Loading verbessert typischerweise sowohl LCP als auch CLS gleichzeitig.

7. Content Negotiation via nginx Accept-Header als Alternative

Statt WebP-Bildformate explizit im Markup über das picture-Element auszuweisen, kann nginx WebP auch transparent per Content Negotiation ausliefern. Moderne Browser senden im Accept-Header image/webp mit, wenn sie das Format unterstützen. Ein map-Block prüft diesen Header und liefert bei vorhandener und passender WebP-Datei diese anstelle des angefragten JPEGs oder PNGs aus, ohne dass das Template angepasst werden muss.

Der Vorteil dieser Methode liegt in der Entkopplung vom Frontend-Code, der Nachteil in der zusätzlichen nginx-Konfigurationskomplexität und einem fehleranfälligeren Caching-Verhalten, da Vary: Accept gesetzt werden muss, damit CDN und Browser-Cache pro Accept-Header unterschiedliche Antworten vorhalten. Für die meisten Hyvä-Projekte bleibt das picture-Element die robustere Wahl, die nginx-Variante eignet sich als zusätzliche Absicherung für Alt-Templates ohne Markup-Anpassung.

# nginx.conf.d/webp.conf - content negotiation via Accept header
map $http_accept $webp_suffix {
    default   "";
    "~*webp"  ".webp";
}

server {
    # ... existing Magento server block ...

    location ~* ^/media/catalog/product/(.+)\.(jpe?g|png)$ {
        add_header Vary Accept;
        try_files /media/catalog/product/$1.$2$webp_suffix $uri =404;
    }
}

8. Rollback-Strategie, wenn die WebP-Konvertierung fehlschlägt

Eine WebP-Konvertierung darf den Storefront niemals blockieren. Schlägt cwebp oder sharp für ein einzelnes Bild fehl, etwa bei einer beschädigten Bilddatei oder einem exotischen Farbprofil, darf das Deploy-Skript weder abbrechen noch eine leere oder halbfertige WebP-Datei stehen lassen. Das Konvertierungsskript aus Abschnitt 4 löscht deshalb bei einem Fehler explizit die Zieldatei und protokolliert den Vorfall, statt das Skript mit set -e zum Absturz zu bringen.

Im Frontend greift der Fallback-Mechanismus des picture-Elements automatisch: Existiert keine WebP-Datei, liefert der Browser einfach den img-Fallback aus, ganz ohne 404-Fehler im Rendering, sofern die WebP-URL serverseitig auf Existenz geprüft und andernfalls gar nicht erst als source ausgegeben wird. Diese doppelte Absicherung, sauberes Fehlerhandling im Build-Schritt plus bedingtes Markup im Template, macht die WebP-Konvertierung risikofrei für den Livebetrieb.

9. WebP-Konvertierung im Vergleich: vorher und nachher

Der Effekt einer automatisierten WebP-Konvertierung lässt sich am besten anhand konkreter Messwerte aus einem typischen Kategorie- und Produktseiten-Setup zeigen.

Die Zahlen stammen aus wiederholten PageSpeed-Insights-Messungen eines mittelgroßen Magento-Katalogs mit rund 3.000 Produkten. Der Wartungsaufwand für die WebP-Konvertierung reduziert sich nach der Erstintegration auf das reine Ausführen eines bereits vorhandenen Deploy-Schritts, ohne dass Redakteure oder Entwickler manuell eingreifen müssen.

10. Zusammenfassung

Eine automatisierte WebP-Konvertierung im Hyvä-Build-Prozess löst ein konkretes Performance-Problem: Katalog- und CMS-Bilder werden ohne manuellen Aufwand 25 bis 35 Prozent kleiner ausgeliefert, ohne die visuelle Qualität sichtbar zu verschlechtern. Das picture-Element mit WebP-Source und klassischem Fallback stellt sicher, dass ältere Browser und Crawler weiterhin ein funktionierendes Bild erhalten. Ein Build-Schritt mit cwebp oder sharp, fest in die Deploy-Sequenz zwischen Static-Content-Deploy und Cache-Flush integriert, macht die Konvertierung reproduzierbar und automatisch.

Entscheidend für den produktiven Einsatz ist die Fehlerbehandlung: Eine WebP-Konvertierung darf niemals den Storefront blockieren, wenn ein einzelnes Bild nicht konvertiert werden kann. Zusammen mit Lazy Loading und korrekten Bilddimensionen wirkt sich die Umstellung direkt und messbar auf LCP und CLS aus. nginx-basierte Content Negotiation ist eine sinnvolle Ergänzung für Alt-Templates, ersetzt aber im Hyvä-Kontext nicht das explizite Markup.

11. FAQ: WebP-Konvertierung im Hyvä-Theme automatisieren