Tailwind CSS v4: Migrationsleitfaden und neue Funktionen

Tailwind CSS v4 ist die bedeutendste Neufassung seit Einführung des Frameworks. Die JavaScript-Konfigurationsdatei ist weg – ersetzt durch eine CSS-First-Konfiguration mit benutzerdefinierten Eigenschaften. Die Klassen-API ist weitgehend unverändert, aber die Interna sind völlig neu: eine Rust-basierte Engine (oxide), erstklassige Unterstützung für den P3-Farbraum, native Containerabfragen und eine Build-Pipeline, die sich direkt in CSS und nicht über PostCSS-Plugins integriert.

In diesem Leitfaden erfahren Sie, was sich geändert hat, warum es geändert wurde und wie Sie eine echte Produktionsanwendung von Tailwind v3 auf v4 migrieren. Wir besprechen die bahnbrechenden Änderungen, die Sie aus der Fassung bringen werden, und die neuen Funktionen, die es wert sind, sofort übernommen zu werden.

Wichtige Erkenntnisse

– tailwind.config.js ist veraltet – die Konfiguration wird mithilfe der @theme-Direktive nach CSS verschoben – Import geändert von @tailwind base/components/utilities zu einem einzelnen @import "tailwindcss" – Benutzerdefinierte Farben verwenden jetzt benutzerdefinierte CSS-Eigenschaften im Namensraum --color-* – Die content-Konfiguration erfolgt automatisch – Tailwind v4 scannt Dateien automatisch über Glob – Containerabfragen sind jetzt mit den Varianten @container und @sm:, @lg: integriert

• Unterstützung des P3-Farbraums über den Farbraum oklch() für alle integrierten Farben
• @apply funktioniert immer noch, ist jedoch bei benutzerdefinierten CSS-Eigenschaften weniger erforderlich
• Die JIT-Engine wird durch Oxide (Rust) ersetzt – eine deutlich schnellere Kompilierung

---

Was hat sich geändert und warum

Tailwind v3 verwendete PostCSS als Verarbeitungspipeline, eine JavaScript-Konfigurationsdatei und generierte Dienstprogrammklassen über eine in JavaScript geschriebene JIT-Engine. Das hat gut funktioniert, hatte aber Einschränkungen:

– Für die Konfiguration ist JavaScript erforderlich, sodass der Zugriff über reine CSS-Tools nicht möglich ist – Benutzerdefinierte Eigenschaften mussten separat von der Tailwind-Konfiguration festgelegt werden

• Für Containerabfragen war ein Plugin erforderlich
• Das Farbsystem unterstützte den P3-Farbraum nicht

Tailwind v4 behebt all diese Probleme, indem es die Konfiguration in CSS selbst verlagert, das native CSS-System für benutzerdefinierte Eigenschaften des Browsers verwendet und die Engine in Rust für 5- bis 10-mal schnellere Builds neu schreibt.

---

Installation

# Tailwind v4
pnpm add tailwindcss@^4.0.0 @tailwindcss/vite

# For Next.js
pnpm add tailwindcss@^4.0.0 @tailwindcss/postcss

Das @tailwindcss/vite-Plugin lässt sich direkt in Vite integrieren. Verwenden Sie für Next.js (das PostCSS intern verwendet) @tailwindcss/postcss.

---

CSS-First-Konfiguration

Dies ist die größte konzeptionelle Änderung. Ihr globals.css wird zur Quelle der Wahrheit für die Tailwind-Konfiguration:

/* Before: globals.css with v3 */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* After: globals.css with v4 */
@import "tailwindcss";

/* Theme configuration replaces tailwind.config.js */
@theme {
  /* Custom colors as CSS custom properties */
  --color-brand-50: oklch(97% 0.02 250);
  --color-brand-100: oklch(94% 0.04 250);
  --color-brand-500: oklch(62% 0.18 250);
  --color-brand-900: oklch(28% 0.09 250);

  /* Custom font families */
  --font-sans: 'Inter', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', monospace;

  /* Custom spacing */
  --spacing-18: 4.5rem;
  --spacing-88: 22rem;

  /* Custom breakpoints */
  --breakpoint-3xl: 1920px;

  /* Custom shadows */
  --shadow-card: 0 1px 3px oklch(0% 0 0 / 12%), 0 1px 2px oklch(0% 0 0 / 8%);
}

Ihr tailwind.config.js kann gelöscht (oder vorerst behalten werden – v4 unterstützt beides während der Migration).

---

Inhaltserkennung

Tailwind v4 erkennt Vorlagendateien automatisch. Die content-Konfiguration, die Sie in Version 3 sorgfältig gepflegt haben, ist weg:

// v3 tailwind.config.js — you needed this
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx}',
  ],
  // ...
}

In v4 scannt Tailwind Ihr Projekt automatisch unter Verwendung sinnvoller Standardeinstellungen. Wenn Sie Dateien an ungewöhnlichen Speicherorten haben, können Sie diese explizit einschließen:

@import "tailwindcss";
@source "../scripts/*.ts"; /* Scan additional paths */
@source "../../packages/ui/src/**/*.tsx"; /* Monorepo workspace packages */

---

PostCSS-Konfigurationsaktualisierung

Aktualisieren Sie für Next.js-Projekte (und jedes PostCSS-basierte Setup) Ihre PostCSS-Konfiguration:

// Before: postcss.config.js with v3
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};

// After: postcss.config.mjs with v4
export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

autoprefixer ist standardmäßig in @tailwindcss/postcss enthalten. Entfernen Sie die separate autoprefixer-Abhängigkeit.

---

Farbsystem: OKLCH

Tailwind v4 verwendet OKLCH für seine integrierte Farbpalette. OKLCH ist ein wahrnehmungsmäßig einheitlicher Farbraum – die Anpassung der Helligkeit sieht für das menschliche Auge im Gegensatz zu HSL tatsächlich wie gleiche Schritte aus.

/* v4 colors use OKLCH internally */
/* bg-blue-500 generates: */
background-color: oklch(62.8% 0.258 264.1);

/* Custom colors with OKLCH */
@theme {
  --color-ecosire-amber: oklch(78% 0.18 80);
  --color-ecosire-navy: oklch(22% 0.04 250);
}

Für Displays mit größerem Farbumfang (die meisten modernen Telefone und Macs) ermöglicht OKLCH Farben, die sRGB einfach nicht darstellen kann. Die oklch()-Werte werden für Displays, die P3 nicht unterstützen, automatisch in rgb() konvertiert.

---

Containerabfragen – Integriert

Containerabfragen sind in Version 4 jetzt erstklassig. Kein Plugin erforderlich:

/* Define a container */
.card-wrapper {
  container-type: inline-size;
  container-name: card;
}

<!-- Responsive based on parent container, not viewport -->
<div class="card-wrapper">
  <div class="@sm:flex-row @lg:grid-cols-3 flex flex-col">
    <!-- Layout changes based on container width, not screen width -->
  </div>
</div>

Dies ermöglicht Reaktionsfähigkeit auf Komponentenebene – eine Seitenleistenkarte und eine Karte in voller Breite können unterschiedliche Layouts ohne separates CSS haben.

Mit benannten Containern können Sie gezielt auf bestimmte Vorfahren abzielen:

<div class="card-wrapper [container-name:card]">
  <div class="@card/sm:text-lg text-base">
    Responsive to the 'card' container
  </div>
</div>

---

Integration benutzerdefinierter CSS-Eigenschaften

In @theme definierte benutzerdefinierte Eigenschaften sind überall zugänglich – CSS, JavaScript und Designtools, die CSS-Variablen lesen:

@theme {
  --color-primary: oklch(62% 0.18 250);
  --spacing-section: 5rem;
}

// Access in JavaScript/TypeScript
const style = getComputedStyle(document.documentElement);
const primary = style.getPropertyValue('--color-primary');

<!-- Use in inline styles -->
<div style={{ color: 'var(--color-primary)' }}>
  Themed content
</div>

Dies ersetzt das Muster der Verwaltung paralleler Werte in tailwind.config.js und einer tokens.ts-Datei – es gibt jetzt eine einzige Quelle der Wahrheit in CSS.

---

Breaking Changes

1. Änderungen an der Plugin-API

v3-Plugins, die addBase, addComponents, addUtilities verwenden, sind mit v4 nicht kompatibel. Schreiben Sie sie mit dem neuen Ebenensystem als CSS um:

/* v3 plugin equivalent in v4 CSS */
@layer base {
  h1 {
    @apply text-3xl font-bold;
  }
}

@layer components {
  .btn {
    @apply px-4 py-2 rounded-lg font-medium;
  }
}

2. @apply mit benutzerdefinierten Klassen

@apply mit Nicht-Tailwind-Klassen ist in Version 4 stärker eingeschränkt. Verwenden Sie @apply nur mit tatsächlichen Dienstprogrammklassen:

/* This works in v4 */
.btn-primary {
  @apply bg-blue-500 text-white px-4 py-2 rounded-lg;
}

/* This is deprecated — use regular CSS instead */
.btn-primary {
  @apply custom-shadow; /* custom-shadow is not a Tailwind utility */
}

3. tailwind.config.js theme.extend ist weg

Die Konfiguration in JS ist nicht mehr der primäre Pfad. Verwenden Sie @theme in CSS. Wenn Sie beides haben, hat die CSS-Konfiguration Vorrang.

4. Benennung der Standardfarbpalette

In Version 4 wurden einige Farbnamen geändert. Führen Sie das offizielle Codemod aus, um sie zu fangen:

npx @tailwindcss/upgrade@next --config tailwind.config.js

---

Migrationsstrategie

Bei einer großen Produktionsanwendung migrieren Sie schrittweise:

Phase 1: Update-Installation

pnpm remove tailwindcss autoprefixer postcss
pnpm add tailwindcss@^4.0.0 @tailwindcss/postcss

Aktualisieren Sie postcss.config.mjs:

export default {
  plugins: { '@tailwindcss/postcss': {} },
};

Aktualisieren Sie globals.css:

/* Replace the three @tailwind directives */
@import "tailwindcss";

Phase 2: Codemod ausführen

npx @tailwindcss/upgrade@next

Dadurch wird der Großteil der Migration automatisiert: Farbnamen werden aktualisiert, Konfigurationen werden in CSS konvertiert und Probleme werden markiert, die manuelle Aufmerksamkeit erfordern.

Phase 3: Konfiguration nach CSS verschieben

Nehmen Sie Ihre tailwind.config.js-Designwerte und verschieben Sie sie in Ihrem CSS nach @theme. Löschen Sie die Konfigurationsdatei nach der Überprüfung.

Phase 4: Neue Funktionen übernehmen

Ersetzen Sie ansichtsfensterbasierte reaktionsfähige Haltepunkte gegebenenfalls durch Containerabfragen. Übernehmen Sie OKLCH für benutzerdefinierte Farben, um P3-Farbraumunterstützung zu erhalten.

---

Leistungsverbesserungen

Die Oxide-Engine (Rust) von Tailwind v4 liefert messbar schnellere Builds:

Bei großen Anwendungen bedeutet dies eine spürbar schnellere HMR in der Entwicklung und deutlich kürzere CI-Erstellungszeiten.

---

Migrationsbeispiel aus der Praxis

Hier ist ein praktisches Vorher/Nachher für die Basiskonfiguration eines Designsystems:

// Before: tailwind.config.js (v3)
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: {
          50: '#fef3c7',
          500: '#f59e0b',
          900: '#78350f',
        },
      },
      fontFamily: {
        sans: ['Inter', 'system-ui'],
      },
      boxShadow: {
        card: '0 1px 3px rgba(0,0,0,0.12)',
      },
    },
  },
  plugins: [
    require('@tailwindcss/typography'),
    require('@tailwindcss/forms'),
  ],
};

/* After: globals.css (v4) */
@import "tailwindcss";
@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/forms";

@theme {
  --color-brand-50: oklch(97% 0.04 85);
  --color-brand-500: oklch(78% 0.18 85);
  --color-brand-900: oklch(33% 0.08 85);

  --font-sans: 'Inter', system-ui, sans-serif;

  --shadow-card: 0 1px 3px oklch(0% 0 0 / 12%);
}

Die CSS-native Konfiguration ist prägnanter und eliminiert die node_modules-Abhängigkeit zum Lesen der Konfiguration.

---

Häufig gestellte Fragen

Muss ich tailwind.config.js sofort löschen?

Nein – Tailwind v4 unterstützt während der Migration gleichzeitig sowohl die JS-Konfiguration als auch die CSS-Konfiguration. Die JS-Konfiguration funktioniert immer noch, aber Funktionen wie @theme in CSS sind nur ohne sie verfügbar. Schrittweise migrieren: Erstellen Sie zunächst die App mit Version 4, verschieben Sie dann die Konfiguration schrittweise auf CSS und löschen Sie dann die JS-Konfiguration, wenn Sie sicher sind.

Funktionieren meine vorhandenen Tailwind v3-Klassen weiterhin in v4?

Die überwiegende Mehrheit der Utility-Klassen bleibt unverändert. Einige Farbnamen wurden aktualisiert (in manchen Kontexten grau → neutral) und einige veraltete Dienstprogramme wurden entfernt. Führen Sie npx @tailwindcss/upgrade@next aus, um die meisten Probleme automatisch zu erkennen. Die Hauptinkompatibilitäten liegen in der Konfiguration von Plugins und benutzerdefinierten Themes, nicht in der Art und Weise, wie Sie Klassen in HTML/JSX verwenden.

Wird OKLCH in allen Browsern unterstützt?

OKLCH wird in allen modernen Browsern unterstützt (Chrome 111+, Firefox 113+, Safari 15.4+). Tailwind v4 generiert bei Bedarf Fallbacks für ältere Browser. Für den P3-Farbraum (die erweiterten Farben) erfordert die Unterstützung sowohl eine Anzeige mit großem Farbraum als auch einen unterstützenden Browser – Tailwind generiert rgb()-Fallbacks für Anzeigen mit engerem Farbraum.

Wie verwende ich Tailwind v4 mit shadcn/ui?

shadcn/ui 2.0+ unterstützt Tailwind v4. Aktualisieren Sie Ihren components.json, um das v4-CSS-Variablenformat zu verwenden. Die Komponentenbibliothek verwendet benutzerdefinierte CSS-Eigenschaften für die Gestaltung, die auf natürliche Weise dem @theme-System von Tailwind v4 zugeordnet werden. Führen Sie npx shadcn@latest init in einem vorhandenen Projekt aus, um die v4-kompatible Konfiguration zu erhalten.

Gibt es TypeScript-Typen für die neue Konfiguration?

Die Konfiguration von Tailwind v4 ist CSS, daher gibt es keine TypeScript-Typen für die Konfiguration selbst. Die IDE-Unterstützung kommt von CSS-Sprachdiensten, die benutzerdefinierte Eigenschaften verstehen. Für den Zugriff auf Designwerte in TypeScript (für Diagramme, Animationen usw.) verwenden Sie getComputedStyle, um benutzerdefinierte CSS-Eigenschaften zur Laufzeit zu lesen, oder generieren Sie im Rahmen Ihres Builds eine Token-Datei aus Ihrem CSS.

---

Nächste Schritte

Tailwind CSS v4 ist ein bedeutendes Upgrade, das sich für neue Projekte und die Planung bestehender Projekte lohnt. Der Frontend-Stack von ECOSIRE führt Tailwind CSS v4.1 in der Produktion in einer 249-seitigen Next.js 16-Anwendung mit einem umfassenden Designsystem aus.

Benötigen Sie Hilfe bei einer Tailwind v4-Migration oder möchten Sie ein von Grund auf neu entwickeltes Designsystem? [Entdecken Sie unsere Frontend-Engineering-Dienste] (/services), um zu sehen, wie wir Ihnen helfen können.