Tailwind v4 und Alpine.js: den CSS-First-Workflow kombinieren

1. Abschied von tailwind.config.js: was @theme wirklich ändert

Bis Tailwind v3 lag die gesamte Design-Konfiguration, Farben, Abstände, Breakpoints, Schriftgrößen, in einer JavaScript-Datei, die beim Build ausgewertet wurde. Jeder, der programmatisch auf diese Werte zugreifen wollte, etwa um in einer Alpine-Komponente die aktuelle Breakpoint-Grenze für eine Berechnung zu kennen, musste entweder die Werte manuell duplizieren oder resolveConfig() in einem separaten Build-Schritt nutzen, um sie als JSON verfügbar zu machen.

Tailwind v4 kehrt dieses Prinzip um: Die Konfiguration lebt jetzt als @theme-Block direkt in der CSS-Einstiegsdatei und wird zu echten CSS-Custom-Properties kompiliert. Aus theme.colors.teal.500 in der alten Config wird --color-teal-500 im kompilierten CSS. Das bedeutet: Diese Werte sind zur Laufzeit im Browser über getComputedStyle() direkt lesbar, ganz ohne separaten JSON-Export oder Build-Schritt, was für Alpine-Komponenten ein deutlich direkterer Zugriffsweg ist als vorher.

/* app/design/frontend/Mironsoft/default/web/tailwind/tailwind-source.css */
@import "tailwindcss";

@theme {
  --color-brand-accent: oklch(0.72 0.19 42);
  --breakpoint-shop-nav: 64rem;
  --spacing-card-gap: 1.25rem;
}

2. CSS-Variablen statt theme()-Funktion: der neue Zugriffsweg für Alpine

In Tailwind v3 gab es in eigenem CSS gelegentlich die Funktion theme('colors.teal.500'), um Konfigurationswerte außerhalb von Utility-Klassen zu nutzen. Diese Funktion existiert in v4 zwar noch für Rückwärtskompatibilität, ist aber nicht mehr der empfohlene Weg. Stattdessen greift man direkt auf die generierte CSS-Variable zu, etwa mit var(--color-brand-accent), sowohl im eigenen CSS als auch, und das ist der entscheidende Unterschied, direkt aus Alpine.js heraus über die DOM-API.

Für eine Alpine-Komponente bedeutet das: Statt eine Farbe oder einen Breakpoint-Wert in einer separaten JS-Konstante zu duplizieren, liest man ihn zur Laufzeit direkt aus dem berechneten Stil des Root-Elements. Das eliminiert eine ganze Klasse von Inkonsistenz-Bugs, bei denen die JS-Kopie eines Design-Tokens nach einem Redesign nicht mehr mit dem tatsächlichen CSS-Wert übereinstimmt, weil es schlicht keine zweite Quelle mehr gibt, die veralten könnte.

// Alpine-Komponente liest ein Design-Token direkt aus dem CSS
Alpine.data('accentAwareBanner', () => ({
  accentColor: '',
  init() {
    const styles = getComputedStyle(document.documentElement);
    this.accentColor = styles.getPropertyValue('--color-brand-accent').trim();
  },
}));

3. Praxisbeispiel: dynamische Akzentfarbe über CSS-Variablen und x-bind:style

Ein konkreter Anwendungsfall: Ein Kampagnen-Banner soll seine Akzentfarbe je nach aktiver Produktkategorie wechseln, wobei die verfügbaren Farben als Tailwind-v4-Theme-Tokens gepflegt werden. Statt eine Liste fester Tailwind-Klassen wie bg-teal-500, bg-orange-500 im JavaScript zu verwalten und dynamisch zusammenzusetzen, was wie im nächsten Abschnitt beschrieben mit v4s Content-Erkennung kollidiert, bindet man die Farbe direkt als CSS-Variable über x-bind:style.

Der Vorteil dieser Herangehensweise liegt darin, dass die Utility-Klasse im Template statisch und damit für Tailwinds Scanner sichtbar bleibt, während nur der Wert der CSS-Variable sich dynamisch ändert. Damit verbindet man die Robustheit von Tailwinds statischer Analyse mit der Flexibilität eines echten Laufzeitzustands, ohne einen der beiden Vorteile aufzugeben.

<div
  x-data="{ accent: '--color-teal-500' }"
  x-bind:style="{ '--banner-accent': `var(${accent})` }"
  class="rounded-lg p-6 border-l-4"
  style="border-color: var(--banner-accent, var(--color-brand-accent))"
>
  <button x-on:click="accent = '--color-orange-500'" class="text-sm underline">
    Kategorie wechseln
  </button>
</div>

4. Automatische Content-Erkennung und dynamisch zusammengesetzte Klassennamen

Tailwind v4 scannt Quelldateien automatisch nach Klassennamen und benötigt dafür anders als bei v3 keine explizite content-Liste mehr in der Config. Das funktioniert zuverlässig, solange Klassennamen als vollständige, unveränderte Zeichenketten im Quelltext stehen. Für Alpine-Komponenten, die Klassen dynamisch aus Teilstrings zusammenbauen, etwa `bg-${color}-500`, ist das ein Problem, denn der Scanner sieht nur das Template mit der Zeichenkette und kann die Laufzeitkombination nicht auflösen.

Die zuverlässige Lösung ist, alle tatsächlich benötigten Klassenkombinationen als vollständige, statische Strings irgendwo im Quelltext vorzuhalten, etwa in einer Kommentarzeile oder einer Lookup-Tabelle im selben Template, damit der Scanner sie erkennt. Noch robuster, und im CSS-first-Kontext von v4 der naheliegendere Weg, ist es, wie im vorherigen Abschnitt gezeigt, auf feste Klassennamen zu verzichten und stattdessen mit CSS-Variablen zu arbeiten, die sich unabhängig vom Scanner zur Laufzeit ändern lassen.

5. Migrationsaufwand: was beim Umstieg von v3-Alpine-Setups zu beachten ist

Beim Umstieg eines bestehenden Hyvä- oder Alpine-Projekts von Tailwind v3 auf v4 lohnt sich zuerst eine Bestandsaufnahme aller Stellen, an denen JavaScript, und damit auch Alpine-Komponenten, auf Werte aus tailwind.config.js zugegriffen haben. Häufig betrifft das Breakpoint-Werte für window.matchMedia()-Aufrufe in Alpine-Komponenten oder Farbwerte, die für Canvas- oder SVG-Zeichnungen dynamisch gebraucht werden.

Jede dieser Stellen muss auf den Zugriff über getComputedStyle() und CSS-Custom-Properties umgestellt werden, was in der Praxis meist eine kleine, wiederverwendbare Hilfsfunktion in der Alpine-Codebasis wert ist. Parallel dazu lohnt sich ein Blick auf alle dynamisch zusammengesetzten Klassenstrings im Projekt, da diese unter v4s automatischer Content-Erkennung, wie oben beschrieben, am ehesten unbemerkt brechen und erst in Produktion als fehlendes Styling auffallen.

6. @apply und Komponenten-Klassen im CSS-first-Workflow

Für wiederkehrende Kombinationen aus Utility-Klassen, die in mehreren Alpine-Komponenten auftauchen, bleibt @apply in Tailwind v4 nutzbar, allerdings im CSS-first-Geist am besten innerhalb eines @layer components-Blocks direkt neben dem @theme-Block gepflegt, statt über verstreute Utility-Ketten im HTML. Das hält Alpine-Templates lesbar, gerade wenn eine Komponente wie ein Akkordeon oder ein Dropdown mehrere Zustände mit jeweils eigenen Klassenkombinationen hat.

Wichtig dabei: @apply löst zur Build-Zeit auf und kennt daher keinen Laufzeitzustand aus Alpine. Für Klassen, die sich abhängig von x-data-Zustand ändern sollen, bleibt weiterhin x-bind:class nötig, @apply-Komponentenklassen eignen sich nur für den statischen Anteil des Markups, der unabhängig vom Alpine-Zustand immer gleich aussieht.

@layer components {
  .accordion-panel {
    @apply rounded-lg border border-gray-200 px-4 py-3 transition-colors;
  }
}

7. Besonderheiten im Hyvä/Magento-Kontext

In einem Hyvä-Theme wird die @theme-Konfiguration in der Regel in einer projektspezifischen CSS-Quelldatei unterhalb von web/tailwind/ gepflegt, die vom Parent-Theme geerbte Werte per @import übernimmt und punktuell überschreibt. Da Hyvä auf strikte Content Security Policy setzt, ändert sich am Umgang mit Inline-Skripten durch v4 nichts, jede Alpine-Komponente, die CSS-Variablen ausliest, bleibt ein ganz normales <script>-Snippet, das wie gewohnt über $hyvaCsp->registerInlineScript() registriert wird.

Ein praktischer Vorteil im Magento-Kontext: Da Shop-Betreiber häufig pro Store-View oder Website unterschiedliche Akzentfarben brauchen, lassen sich diese jetzt sauber als CSS-Custom-Properties pro Theme-Variante überschreiben, ohne dass eine einzige Zeile Alpine-JavaScript angefasst werden muss, solange die Komponenten konsequent über var() statt über feste Klassennamen arbeiten.

8. Build-Performance: Oxide-Engine und der Effekt auf den Entwicklungs-Workflow

Tailwind v4 nutzt eine neue, in Rust geschriebene Build-Engine, die intern als Oxide bekannt ist und gegenüber der v3-Engine deutlich kürzere Build-Zeiten liefert, insbesondere bei inkrementellen Rebuilds während der Entwicklung. Für ein Hyvä-Projekt mit vielen Alpine-Komponenten und häufigen Style-Anpassungen bedeutet das spürbar kürzere Wartezeiten im Watch-Modus, was den Feedback-Zyklus beim Feintuning dynamischer Klassen und CSS-Variablen merklich beschleunigt.

Ein Nebeneffekt der schnelleren, direkteren Content-Erkennung ist, dass Fehler durch dynamisch zusammengesetzte Klassennamen schneller sichtbar werden, weil der Build nicht mehr durch lange Wartezeiten kaschiert wird. Wer die im vierten Abschnitt beschriebene Umstellung auf CSS-Variablen konsequent umsetzt, profitiert doppelt: schnellere Builds und weniger Fälle, in denen der Scanner überhaupt etwas übersehen könnte.

9. Checkliste für einen sauberen Umstieg

Vor dem Umstieg lohnt sich eine kurze, geordnete Vorgehensweise: zuerst alle JS-Zugriffe auf die alte tailwind.config.js auflisten, dann jede Fundstelle einzeln auf CSS-Custom-Properties umstellen, anschließend alle dynamisch zusammengesetzten Klassenstrings in Alpine-Templates suchen und durch CSS-Variablen-Bindings ersetzen, und zuletzt den Build im Watch-Modus laufen lassen und visuell jede betroffene Komponente gegenprüfen.

Wer diese Reihenfolge einhält, vermeidet das häufigste Migrationsproblem: dass ein Teil der Klassen im Produktions-Build plötzlich fehlt, weil der Scanner eine dynamisch gebaute Kombination nicht mehr erkannt hat, ein Fehler, der in der lokalen Entwicklung mit ungepurgtem CSS oft unsichtbar bleibt und erst nach dem Deploy auffällt.

10. Zusammenfassung

11. FAQ: Tailwind v4 mit Alpine.js