CI-Pipeline für den Tailwind-Build im Hyvä-Theme einrichten

1. Der manuelle Tailwind-Build als unterschätztes Deployment-Risiko

In vielen Hyvä-Projekten läuft bin/npm --prefix app/design/frontend/[Vendor]/[Theme]/web/tailwind run build noch von Hand auf dem Rechner der Person, die zuletzt am Frontend gearbeitet hat, bevor das Ergebnis eingecheckt oder direkt deployt wird. Das funktioniert, solange nur eine Person am Theme arbeitet, wird aber schnell zur Fehlerquelle, sobald mehrere Entwickler parallel an unterschiedlichen Branches arbeiten und jeder eine leicht andere lokale Node- oder npm-Version installiert hat.

Der eigentliche Kern des Problems ist, dass ein manueller Build-Schritt niemals verlässlich reproduzierbar ist, weil er von Umgebungsfaktoren abhängt, die außerhalb des Git-Repositorys liegen. Eine CI-Pipeline eliminiert genau diese Variable, indem sie den Build in einer exakt definierten, versionierten Umgebung ausführt, die für jeden Commit identisch ist, unabhängig davon, wer den Code geschrieben hat oder welches Betriebssystem lokal im Einsatz ist.

2. Den Tailwind-Build als eigene, reproduzierbare CI-Stage definieren

Der sauberste Ansatz ist eine dedizierte Pipeline-Stage, die ausschließlich für den Tailwind-Build zuständig ist und klar vor dem Deployment-Job steht, statt den Build als Nebeneffekt eines größeren Skripts zu verstecken. Diese Stage checkt das Repository aus, installiert die exakt in package-lock.json fixierten Abhängigkeiten und führt den Production-Build mit denselben Flags aus, die auch in der Deploy-Sequenz aus der Projektdokumentation vorgesehen sind.

Wichtig ist, dass diese Stage in einem Docker-Image mit exakt derselben Node-Version läuft, die auch im Mark-Shust-Setup verwendet wird, damit lokale Entwicklung und CI dasselbe Ergebnis produzieren. Eine Abweichung an dieser Stelle führt sonst zu dem klassischen Muster, dass ein Build lokal fehlerfrei durchläuft, in der Pipeline aber mit einer anderen Tailwind-Engine-Version subtil anderes CSS erzeugt.

tailwind-build:
  stage: build
  image: node:20-bookworm-slim
  script:
    - cd src/app/design/frontend/Mironsoft/default/web/tailwind
    - npm ci
    - npm run build
  artifacts:
    paths:
      - src/app/design/frontend/Mironsoft/default/web/css/styles.css
    expire_in: 1 day

3. Build-Cache zwischen Pipeline-Läufen wirksam einrichten

Ohne Cache installiert jeder Pipeline-Lauf alle npm-Abhängigkeiten komplett neu, obwohl sich package-lock.json zwischen zwei Commits meist gar nicht ändert. GitLab CI erlaubt es, den node_modules-Ordner über einen Cache-Key zu persistieren, der aus dem Hash von package-lock.json gebildet wird, sodass ein Cache-Treffer nur dann verworfen wird, wenn sich tatsächlich eine Abhängigkeit geändert hat, statt bei jedem einzelnen Commit.

Zusätzlich zum node_modules-Cache lohnt sich ein zweiter Cache für den internen Tailwind-Build-Cache, den die Engine bei wiederholten Läufen nutzt, um bereits einmal verarbeitete Utility-Klassen nicht erneut zu berechnen. In der Praxis reduziert die Kombination beider Cache-Ebenen die Build-Zeit einer typischen Hyvä-Pipeline von mehreren Minuten auf wenige Sekunden bei unveränderten Abhängigkeiten.

tailwind-build:
  stage: build
  image: node:20-bookworm-slim
  cache:
    key:
      files:
        - src/app/design/frontend/Mironsoft/default/web/tailwind/package-lock.json
    paths:
      - src/app/design/frontend/Mironsoft/default/web/tailwind/node_modules/
      - src/app/design/frontend/Mironsoft/default/web/tailwind/.tailwind-cache/
    policy: pull-push
  script:
    - cd src/app/design/frontend/Mironsoft/default/web/tailwind
    - npm ci --prefer-offline
    - npm run build

4. Fehlerhafte Tailwind-Klassen automatisiert vor dem Deployment erkennen

Tailwind v4 scannt den Quellcode statisch nach Klassennamen und kann deshalb dynamisch zusammengesetzte Strings wie class={'text-' + color + '-500'} in einer .phtml-Datei grundsätzlich nicht erkennen, weil der Compiler zur Build-Zeit den tatsächlichen Wert der Variable nicht kennt. Das Resultat ist kein Build-Fehler, sondern ein leises, im schlimmsten Fall erst im Live-Betrieb sichtbares Problem, weil die passende Utility-Klasse im generierten CSS schlicht fehlt.

Ein eigener CI-Schritt, der den Template-Code vor dem Build mit einem einfachen Grep-Muster nach verdächtigen String-Konkatenationen in Klassen-Attributen durchsucht, deckt diese Fälle deutlich früher auf als ein manueller Review. Ergänzend lässt sich die Größe der generierten styles.css gegen eine erwartete Bandbreite prüfen, denn ein plötzlicher, unerklärter Rückgang der Dateigröße deutet häufig darauf hin, dass der Scanner weniger Klassen gefunden hat als im vorherigen Build.

#!/usr/bin/env bash
# ci/check-dynamic-classes.sh
set -euo pipefail

MATCHES=$(grep -rEn "class=[\"'].*\$\{" src/app/design/frontend/Mironsoft/default --include="*.phtml" || true)

if [ -n "$MATCHES" ]; then
  echo "Verdaechtige dynamische Klassen gefunden, die Tailwind beim Purge übersehen kann:"
  echo "$MATCHES"
  exit 1
fi

echo "Keine dynamischen Klassen-Strings gefunden."

5. CSS-Größendiff zwischen Branches als frühes Qualitätssignal

Über die reine Existenz der Datei hinaus lohnt sich ein Vergleich der CSS-Größe zwischen dem aktuellen Merge-Request-Branch und dem main-Branch als Merge-Job-Kommentar, weil ein sprunghafter Anstieg häufig auf versehentlich eingeschleustes, nicht bereinigtes Utility-Markup hinweist, während ein starker Rückgang auf eine fehlerhafte Content-Konfiguration hindeuten kann, die Teile des Templates gar nicht mehr erfasst.

Dieser Diff ersetzt keine inhaltliche Prüfung, liefert aber ein schnelles, automatisiertes Signal dafür, dass sich etwas Grundlegendes am generierten CSS verändert hat, bevor ein Reviewer den eigentlichen Code-Diff überhaupt gelesen hat. Für Teams mit häufigen Tailwind-Config-Änderungen ist dieses Signal oft der erste Hinweis auf ein Problem, das sonst erst im visuellen Review auffallen würde.

6. Den Build in einer isolierten, deterministischen Umgebung ausführen

Ein Docker-Image mit exakt gepinnter Node-Version, das ausschließlich für den Build verwendet wird und keine zusätzlichen global installierten npm-Pakete enthält, verhindert das klassische Problem, dass ein neuerer, lokal installierter Postcss-Plugin-Stand ein anderes Ergebnis erzeugt als die in package-lock.json festgehaltene Version. Diese Isolation ist der eigentliche Kern von Reproduzierbarkeit, nicht nur ein Detail der Pipeline-Konfiguration.

Für Teams, die sowohl die Mironsoft- als auch die Abrams-Vendor-Variante eines Themes pflegen, empfiehlt sich zusätzlich eine Matrix-Konfiguration, die denselben Build-Job für beide Theme-Pfade parallel ausführt, damit ein CSS-Fehler in einer der beiden Varianten nicht erst beim manuellen Deployment der jeweils anderen Variante auffällt.

7. Tailwind-Warnungen konsequent als Pipeline-Fehler behandeln

Die Tailwind-Engine gibt bei unbekannten oder fehlerhaft geschriebenen Utility-Klassen üblicherweise nur eine Warnung auf der Standardausgabe aus, lässt den Build aber trotzdem erfolgreich durchlaufen, weil eine unbekannte Klasse für den Compiler kein technischer Fehler ist. In einer CI-Pipeline sollte dieses Verhalten bewusst verschärft werden, indem die Build-Ausgabe nach bekannten Warnungsmustern durchsucht und der Job bei einem Treffer explizit mit einem Fehlercode beendet wird.

Diese Verschärfung mag zunächst unbequem wirken, weil sie Merge-Requests blockiert, die vorher stillschweigend durchgelaufen wären, verhindert aber zuverlässig, dass eine falsch geschriebene Klasse wie hoverr:bg-blue-500 unbemerkt bis in die Produktion gelangt, wo sie schlicht keine Wirkung zeigt und erst durch einen manuellen visuellen Vergleich auffallen würde.

#!/usr/bin/env bash
set -euo pipefail

npm run build 2>&1 | tee build.log

if grep -qi "warn" build.log; then
  echo "Tailwind-Build hat Warnungen ausgegeben, Pipeline wird als fehlgeschlagen markiert."
  exit 1
fi

8. Das gebaute CSS als Artefakt an den Deploy-Job weitergeben

Ein häufiger Anti-Pattern ist, den Tailwind-Build sowohl in der Test- als auch in der Deploy-Stage erneut auszuführen, weil dadurch nicht nur unnötig Zeit verloren geht, sondern theoretisch auch zwei leicht unterschiedliche CSS-Ergebnisse entstehen könnten, wenn sich zwischen beiden Läufen eine externe Abhängigkeit ändert. Stattdessen sollte der Build genau einmal laufen und das Ergebnis als GitLab-CI-Artefakt an nachfolgende Stages weitergereicht werden.

Die setup:static-content:deploy-Stage aus der Deploy-Sequenz greift dann auf genau diese bereits gebaute styles.css zurück, statt selbst npm-Kommandos auszuführen, wodurch die Verantwortlichkeiten sauber getrennt bleiben: Der Build-Job ist für korrektes CSS zuständig, der Deploy-Job ausschließlich für dessen korrekte Auslieferung in den statischen Magento-Ordnern.

9. Beispielhafte vollständige Pipeline für Tailwind-Build und Deployment

Die folgende, verkürzte Pipeline zeigt das Zusammenspiel aller vorgestellten Bausteine in der richtigen Reihenfolge: Erst der gecachte Build mit Fehlererkennung, dann ein optionaler CSS-Diff-Kommentar für Reviewer, und erst danach der Deploy-Job, der ausschließlich das bereits validierte Artefakt verwendet, statt selbst noch einmal in die Build-Logik einzugreifen.

Dieser Aufbau macht die Pipeline nicht nur schneller, sondern vor allem nachvollziehbarer, weil jeder Job genau eine Verantwortung trägt und im Fehlerfall sofort erkennbar ist, in welcher Phase, Build, Prüfung oder Deployment, ein Problem tatsächlich aufgetreten ist, statt eine einzelne monolithische Stage durchsuchen zu müssen.

stages:
  - build
  - check
  - deploy

tailwind-build:
  stage: build
  image: node:20-bookworm-slim
  cache:
    key: { files: [src/app/design/frontend/Mironsoft/default/web/tailwind/package-lock.json] }
    paths: [src/app/design/frontend/Mironsoft/default/web/tailwind/node_modules/]
  script:
    - cd src/app/design/frontend/Mironsoft/default/web/tailwind && npm ci && npm run build
  artifacts:
    paths: [src/app/design/frontend/Mironsoft/default/web/css/styles.css]

tailwind-css-check:
  stage: check
  needs: [tailwind-build]
  script:
    - bash ci/check-dynamic-classes.sh
    - bash ci/check-css-size.sh

deploy-static-content:
  stage: deploy
  needs: [tailwind-css-check]
  script:
    - bin/magento setup:static-content:deploy de_DE en_US -t Mironsoft/default -f
  only:
    - main

10. Zusammenfassung

11. FAQ: CI-Pipeline für den Tailwind-Build: Das Wichtigste auf einen Blick