Tailwind CSS Migration von v3 zu v4: vollständige Schritt-für-Schritt-Anleitung

1. Warum Tailwind CSS v4 ein Paradigmenwechsel ist

Die Tailwind CSS Migration von v3 zu v4 unterscheidet sich grundlegend von früheren Minor-Updates. In Tailwind CSS v4 wurde die gesamte Architektur neu gedacht: Statt einer JavaScript-Konfigurationsdatei, die das Build-Tool aufruft, lebt die gesamte Konfiguration nun in CSS selbst. Das bedeutet, dass Design-Tokens, Breakpoints, Farben und Custom Utilities direkt im CSS definiert werden – ohne eine einzige Zeile JavaScript. Dieser Ansatz wird als CSS-first bezeichnet und ist das zentrale Merkmal der neuen Version.

Der zweite große Wechsel betrifft den internen Prozessor. Tailwind CSS v4 setzt auf Lightning CSS, einen in Rust geschriebenen CSS-Transformer, der deutlich schneller als der bisherige PostCSS-basierte Workflow ist. Full Builds, die in v3 mehrere Sekunden dauerten, reduzieren sich auf Millisekunden. Das ist besonders für große Projekte mit vielen Custom-Utilities und komplexen Design-Token-Systemen ein erheblicher Vorteil. Die Tailwind CSS Migration lohnt sich also nicht nur wegen neuer Features, sondern auch aus rein pragmatischen Performance-Gründen.

Trotzdem sollte die Migration nicht unterschätzt werden. Wer ein komplexes Design-System auf Basis von tailwind.config.js betreibt, muss alle Konfigurationen in die neue CSS-Syntax übersetzen. Plugins, die in JavaScript geschrieben wurden, müssen ebenfalls umgeschrieben werden. Das automatisierte Upgrade-Tool hilft dabei erheblich, deckt aber nicht alle Edge Cases ab. Eine strukturierte Tailwind CSS Migration mit Testabdeckung ist deshalb wichtiger denn je.

2. Das automatisierte Upgrade-Tool

Tailwind stellt für die Tailwind CSS Migration von v3 auf v4 ein offizielles Upgrade-Tool bereit, das den Großteil der mechanischen Umbenennungen automatisch durchführt. Der Befehl ist denkbar einfach: npx @tailwindcss/upgrade im Projektverzeichnis. Das Tool analysiert alle Template-Dateien, erkennt veraltete Klassen und ersetzt sie durch die neuen Entsprechungen. Es wandelt außerdem die tailwind.config.js in ein CSS-@theme-Block um, soweit das automatisch möglich ist.

Die Grenzen des Tools sind aber reale Grenzen: Komplexe Plugin-Definitionen in JavaScript, dynamisch berechnete Klassenstrings und themenspezifische Extend-Konstrukte müssen manuell nachgearbeitet werden. Das Upgrade-Tool erzeugt eine migration.log-Datei, die alle vorgenommenen Änderungen und alle Stellen auflistet, an denen manuelle Eingriffe nötig sind. Diese Logdatei ist der wichtigste Ausgangspunkt für die manuelle Phase der Tailwind CSS Migration. Es empfiehlt sich, das Tool auf einem separaten Branch auszuführen und die Änderungen commit-weise zu überprüfen.

/* Run the automated migration tool first */
/* npx @tailwindcss/upgrade */

/* BEFORE (v3): tailwind.config.js */
/*
module.exports = {
  content: ['./src/**/*.{html,js}'],
  theme: {
    extend: {
      colors: {
        brand: { 500: '#0ea5e9', 700: '#0369a1' }
      },
      fontFamily: {
        sans: ['Inter', 'sans-serif']
      }
    }
  }
}
*/

/* AFTER (v4): main CSS file — no JS config needed */
@import "tailwindcss";

@theme {
  /* Custom brand colors map directly to CSS custom properties */
  --color-brand-500: #0ea5e9;
  --color-brand-700: #0369a1;

  /* Font family tokens */
  --font-family-sans: Inter, sans-serif;
}

3. CSS-first-Konfiguration: von tailwind.config.js zu @theme

Der wichtigste Schritt bei der Tailwind CSS Migration ist das Verstehen der @theme-Direktive. In Tailwind v4 werden alle Design-Tokens als CSS Custom Properties unter @theme definiert. Tailwind generiert daraus automatisch Utility-Klassen: Aus --color-brand-500: #0ea5e9 entstehen die Klassen text-brand-500, bg-brand-500, border-brand-500 und alle anderen farbbezogenen Utilities. Das Mapping von Token-Namen zu Klassen folgt einem konsistenten Schema, das sich aus dem Variablen-Namen ergibt.

Custom Utilities, die in v3 über addUtilities() in Plugins definiert wurden, werden in v4 mit der @utility-Direktive direkt in CSS geschrieben. Das macht die Definition von Custom-Klassen deutlich näher an Standard-CSS und erfordert kein JavaScript-Wissen mehr. Bestehende @apply-Aufrufe bleiben in v4 grundsätzlich kompatibel, sollten aber bei der Tailwind CSS Migration kritisch überprüft werden – in einigen Fällen ist eine direkte CSS-Regel klarer und performanter. Die @layer-Direktive funktioniert weiterhin, interagiert aber neu mit dem erweiterten Cascade-Layer-System.

Breakpoints und Container-Queries werden in v4 ebenfalls über CSS-Variablen konfiguriert. Der Standard-Breakpoint für md ist als --breakpoint-md: 48rem definiert und kann über @theme überschrieben werden. Diese Durchgängigkeit des CSS-first-Ansatzes ist der eigentliche Kern der neuen Architektur: Alles, was Tailwind über das Projekt wissen muss, steht in der CSS-Datei selbst – keine externe Konfigurationsdatei, kein zweiter Kontext.

4. Lightning CSS statt PostCSS

In Tailwind CSS v4 übernimmt Lightning CSS die Aufgaben, die bisher PostCSS-Plugins erledigten: Autoprefixing, CSS-Nesting, oklab()- und oklch()-Farbfunktionen, logical properties und moderne CSS-Syntax werden alle direkt von Lightning CSS transformiert. Das bedeutet: Wer die Tailwind CSS Migration durchführt, kann postcss-nesting, autoprefixer und ähnliche Plugins aus der Abhängigkeitsliste entfernen. Die postcss.config.js wird deutlich kürzer oder entfällt bei Vite-Projekten vollständig.

Das Tailwind CSS v4 Vite-Plugin @tailwindcss/vite integriert Lightning CSS transparent in den Build-Prozess. Für Projekte ohne Vite gibt es @tailwindcss/postcss, das als PostCSS-Plugin fungiert, intern aber auf Lightning CSS setzt. Bei der Tailwind CSS Migration muss die Wahl des Integrationspfads frühzeitig getroffen werden, da sie die Konfiguration des gesamten Build-Systems beeinflusst. Die Geschwindigkeitsgewinne sind in großen Projekten sofort spürbar: Inkrementelle Rebuilds reduzieren sich typischerweise auf unter 100 Millisekunden.

/* Vite integration — replaces postcss.config.js for most projects */
/* vite.config.ts */
/*
import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [tailwindcss()]
})
*/

/* PostCSS integration (non-Vite projects) */
/* postcss.config.js */
/*
export default {
  plugins: {
    '@tailwindcss/postcss': {}
    // autoprefixer and postcss-nesting are NO LONGER needed
    // Lightning CSS handles all transformations internally
  }
}
*/

/* In your main CSS file — that's all you need */
@import "tailwindcss";

@theme {
  --color-primary: oklch(60% 0.2 250);
  --color-primary-dark: oklch(45% 0.2 250);
}

/* Lightning CSS transforms oklch() automatically for older browsers */
.btn-primary {
  background-color: var(--color-primary);
  &:hover {
    background-color: var(--color-primary-dark);
  }
}

5. Umbenannte und geänderte Utility-Klassen

Neben der Konfigurationsarchitektur enthält die Tailwind CSS Migration eine Reihe von umbenannten Klassen. Die wichtigsten Änderungen betreffen Shadow-Utilities: shadow wurde zu shadow-sm, shadow-sm zu shadow-xs. Das Blur-System wurde analog umbenannt. Die alten Klassenbezeichnungen werden vom automatischen Upgrade-Tool ersetzt, aber Template-Dateien, die Klassen dynamisch zusammensetzen, müssen manuell geprüft werden.

Ring-Utilities haben sich geändert: ring erzeugt jetzt einen 1px-Ring statt 3px wie in v3. Wer den alten visuellen Look beibehalten will, muss auf ring-3 wechseln. Outline-Utilities wurden vereinheitlicht und ersetzen einige der früheren Ring-Patterns. Die Opacity-Utilities wurden in v4 direkt in die betreffenden Klassen integriert: bg-blue-500/50 war zwar schon in v3 möglich, aber in v4 ist dieses Muster die einzige empfohlene Methode für Farbopazität. Die bg-opacity-*-Klassen entfallen. Bei der Tailwind CSS Migration sollte ein globales Suchen nach bg-opacity, text-opacity und border-opacity der erste Schritt sein.

6. Neue Varianten und Selektoren in v4

Tailwind CSS v4 führt mehrere neue Varianten ein, die in v3 nicht verfügbar waren. Die field-sizing-Variante, starting für View Transitions, inert für deaktivierte Elemente und nth-* für CSS-:nth-child()-Selektoren sind in v4 nativ enthalten. Diese Varianten erfordern keine Plugins mehr. Wer in v3 mit Custom Plugins für solche Selektoren gearbeitet hat, kann diese im Rahmen der Tailwind CSS Migration entfernen.

Besonders interessant ist die neue Unterstützung für Container Queries direkt ohne Plugin. In v3 war @tailwindcss/container-queries ein externes Paket. In v4 ist es eingebaut: @container, @sm:text-lg und Named Containers funktionieren out of the box. Das vereinfacht Komponenten-basierte Layouts erheblich, weil Breakpoints nun relativ zum Elternelement statt zum Viewport definiert werden. Bei der Tailwind CSS Migration können Projekte, die das Container-Query-Plugin genutzt haben, dieses aus den Abhängigkeiten entfernen.

7. Plugins migrieren: von JS zu CSS

Wer in v3 Tailwind-Plugins in JavaScript geschrieben hat, steht bei der Tailwind CSS Migration vor der aufwändigsten Aufgabe. Das JavaScript-Plugin-API aus v3 (plugin(({ addUtilities, addComponents, theme }) => {})) existiert in v4 weiterhin für Rückwärtskompatibilität, ist aber nicht mehr der empfohlene Weg. In v4 werden neue Utilities über @utility definiert, neue Komponenten-Klassen über @layer components und Design-Tokens über @theme.

Ein Plugin, das in v3 Custom Utilities per addUtilities registriert hat, wird in v4 zu einem Block in der CSS-Datei. Der Vorteil ist erheblich: Die Utilities sind jetzt standard-CSS und können von Entwicklern gelesen und verstanden werden, die kein JavaScript kennen. Außerdem profitieren sie von der Lightning-CSS-Optimierung. Für komplexe Plugins, die dynamisch aus dem Theme-Objekt lesen (theme('colors.brand')), ist die Migration aufwändiger – hier müssen die CSS Custom Properties direkt verwendet werden, die von @theme erzeugt werden.

/* BEFORE (v3): JavaScript plugin */
/*
const plugin = require('tailwindcss/plugin')
module.exports = {
  plugins: [
    plugin(({ addUtilities }) => {
      addUtilities({
        '.text-balance': { 'text-wrap': 'balance' },
        '.text-pretty': { 'text-wrap': 'pretty' },
      })
    })
  ]
}
*/

/* AFTER (v4): Pure CSS — no plugin needed for most cases */
@import "tailwindcss";

@utility text-balance {
  text-wrap: balance;
}

@utility text-pretty {
  text-wrap: pretty;
}

/* Accessing theme tokens in utilities */
@utility btn-brand {
  background-color: var(--color-brand-500);
  color: white;
  padding: var(--spacing-2) var(--spacing-4);
  border-radius: var(--radius-lg);
}

8. v3 vs. v4 im direkten Vergleich

Die folgende Tabelle zeigt die wichtigsten konzeptuellen Unterschiede zwischen Tailwind CSS v3 und v4, die bei der Tailwind CSS Migration berücksichtigt werden müssen.

9. Migrations-Checkliste für reale Projekte

Eine erfolgreiche Tailwind CSS Migration von v3 zu v4 folgt einer klaren Reihenfolge. Zuerst das Upgrade-Tool auf einem Feature-Branch ausführen und die Log-Datei sichten. Danach die Build-Konfiguration aktualisieren: Vite-Plugin oder PostCSS-Plugin einrichten, PostCSS-Plugins entfernen, die Lightning CSS übernimmt. Anschließend die tailwind.config.js-Reste, die das Tool nicht automatisch übersetzen konnte, manuell in @theme-Blöcke überführen.

Im nächsten Schritt die Suchbegriffe bg-opacity, text-opacity, border-opacity, shadow (standalone) und ring (standalone) im gesamten Codebase durchsuchen und durch die v4-Äquivalente ersetzen. Danach alle JavaScript-Plugins sichten und entscheiden, welche in @utility-Blöcke überführt werden und welche das JavaScript-API aus Kompatibilitätsgründen vorerst behalten. Abschließend visuelle Regressionstests durchführen – Chromatic, Percy oder einfache Screenshot-Vergleiche sichern die UI-Integrität nach der Tailwind CSS Migration.

10. Zusammenfassung

Die Tailwind CSS Migration von v3 zu v4 ist aufwändiger als eine normale Minor-Version, aber die Vorteile rechtfertigen den Aufwand: deutlich schnellere Build-Zeiten durch Lightning CSS, eine einzige Konfigurationsquelle in CSS, eingebaute Container Queries und ein konsistenteres Design-Token-System. Das automatisierte Upgrade-Tool deckt den Großteil der mechanischen Änderungen ab, aber komplexe Plugin-Landschaften und dynamische Klassen-Strings brauchen manuelle Aufmerksamkeit.

Wer die Migration strukturiert angeht – Upgrade-Tool, Build-Konfiguration, manuelle Nacharbeit, visuelle Tests – reduziert das Risiko von Regressionen erheblich. Tailwind CSS v4 ist das stabilste und schnellste Fundament, das Tailwind je geboten hat, und die Investition in die Tailwind CSS Migration zahlt sich für jedes Projekt aus, das länger als ein Jahr im Betrieb bleibt.