Tailwind CSS v4 : guide pratique de la migration
Configuration CSS-native, nouvelles API de variantes, suppression du fichier tailwind.config — tout ce qu'il faut savoir pour migrer sereinement vers Tailwind v4.
Tailwind CSS v4 est sorti, et c'est probablement la mise à jour la plus structurante depuis la version 2.0. Le framework a été réarchitecturé en profondeur, avec un nouveau moteur basé sur des APIs CSS natives qui simplifie considérablement la configuration tout en offrant de meilleures performances.
Ayant migré plusieurs projets ces derniers mois, voici un guide complet de ce qui change, ce qui casse, et comment migrer sans douleur.
Le changement fondamental : la configuration CSS-native
Le plus gros changement, c'est l'abandon du fichier tailwind.config.js au profit d'une configuration directement en CSS. Au lieu de configurer couleurs, polices et breakpoints dans du JavaScript, tout se passe dans votre feuille de style avec des propriétés CSS customs.
Avantages : performance (plus de parsing JS à chaque build), simplicité (une seule syntaxe, celle du CSS), et interopérabilité (vos tokens sont des propriétés CSS utilisables même sans Tailwind).
En v4, la configuration devient :
```css @import "tailwindcss";
@theme { --color-brand-500: #6366f1; --color-brand-600: #4f46e5; --font-family-display: 'Cabinet Grotesk', sans-serif; } ```
La suppression du fichier de configuration JavaScript élimine une couche de complexité qui causait régulièrement des bugs de build.
Les nouvelles APIs de variantes
La directive @apply est dépréciée au profit de @variant :
``css
@variant components {
.card {
border-radius: var(--radius-xl);
background: var(--color-white);
padding: var(--spacing-6);
}
}
``
L'approche est plus explicite, plus proche du CSS natif, et facilite la compréhension de ce que fait réellement chaque règle.
La gestion des couleurs avec oklch
Tailwind v4 adopte l'espace colorimétrique oklch comme standard. C'est un changement important :
- oklch est perceptivement uniforme — une même variation de luminosité est perçue identiquement quelle que soit la teinte, contrairement à HSL
- Meilleure gestion du thème sombre
- Supporté nativement par tous les navigateurs modernes
Vos couleurs migrent vers :
``css
@theme {
--color-primary: oklch(0.55 0.2 265);
--color-accent: oklch(0.7 0.18 180);
}
``
Les breaking changes à anticiper
- La classe
containerdisparaît — utilisezmax-w-*etmx-autodirectement @applyest déprécié — privilégiez les classes dans le HTML ou@variant- Les valeurs par défaut ont été ajustées (palette rafraîchie, espacements normalisés)
- L'intégration Next.js est encore plus simple — le plugin PostCSS devient optionnel
Stratégie de migration
1. Audit des personnalisations dans votre tailwind.config.js
2. Installation de tailwindcss@^4.0.0
3. Conversion des couleurs HEX/RGB en oklch (outil : oklch.com)
4. Remplacement progressif des @apply — composant par composant
5. Tests visuels avec des snapshots (Playwright est excellent pour ça)
Verdict
Pour un nouveau projet : oui sans hésiter. La configuration CSS-native est un progrès objectif.
Pour un projet existant en v3 : nuancé. Si le projet est stable, attendez quelques mois. Si vous démarrez une refonte, la migration est un investissement rentable.
Tailwind v4 n'est pas une révolution cosmétique — c'est une refonte architecturale qui pose les fondations des prochaines années du framework.