Migration vers Tailwind CSS v4 : présentation du moteur Oxide et d’un système de thème basé sur les variables CSS

Tailwind CSS v4 apporte des changements majeurs par rapport à la v3 avec son moteur Oxide basé sur Rust et sa prise en charge intégrée des variables CSS. Voici un résumé des enseignements tirés d’une migration réelle.

Principaux changements de la v4

1. 1Moteur Oxide : basé sur Rust, il rend les builds 5x plus rapides.
2. 2Variables CSS natives : vous pouvez définir des variables directement dans le bloc @theme, tandis que la configuration JS reste facultative.
3. 3Démarrage sans configuration : fonctionne sans tailwind.config.js.
4. 4Container queries standard : aucun plugin séparé n’est nécessaire.
5. 5Utilitaires 3D/subgrid : les fonctionnalités CSS modernes sont largement prises en charge.

Configurer un nouveau projet

/* globals.css */
@import "tailwindcss";

@theme {
  --color-brand: oklch(0.7 0.15 250);
  --font-display: "Pretendard", sans-serif;
  --radius-md: 0.5rem;
}

Avec cette configuration, Tailwind fonctionne facilement même sans tailwind.config.js.

Checklist de migration de la v3 vers la v4

Étape 1 : mettre à niveau

npm install tailwindcss@4 @tailwindcss/postcss@4 --save-dev
# If you use Vite
npm install @tailwindcss/vite --save-dev

Étape 2 : convertir le fichier de configuration

Exécutez npx @tailwindcss/upgrade pour migrer automatiquement tailwind.config.js.

Étape 3 : passer progressivement aux variables CSS

/* v3 approach (can be kept) */
/* theme.extend in tailwind.config.js */

/* v4 approach (recommended) */
@theme {
  --color-primary-500: #3b82f6;
  --breakpoint-xs: 480px;
}

Étape 4 : configuration PostCSS

// postcss.config.js
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
}

Les packages existants tailwindcss et autoprefixer ne sont plus nécessaires, car Oxide gère tout cela.

Principaux changements incompatibles

1. 1Restrictions de @apply : le chaînage de classes arbitraires n’est pas possible ; seule l’utilisation au niveau des tokens est autorisée.
2. 2Option JIT supprimée : il fonctionne toujours en mode JIT, et le mode hérité a été supprimé.
3. 3Utilitaires obsolètes : pour les utilitaires comme flex-shrink-0, seuls les noms raccourcis tels que shrink-0 sont conservés.
4. 4Directives @variants et @responsive supprimées : les media queries doivent utiliser la syntaxe CSS standard.

Comparaison de la vitesse de build en conditions réelles

Pour un projet avec 300 composants :

• v3 + PostCSS : build initial en 8,2 secondes
• v4 + Oxide : build initial en 1,4 seconde
• Builds incrémentaux : la v3 descend à 1,2 seconde, tandis que la v4 descend à 0,3 seconde.

Plus le design system est vaste, plus la différence devient perceptible.

Avantages des thèmes à variables CSS

Les changements de thème sont reflétés immédiatement à l’exécution :

document.documentElement.style.setProperty("--color-brand", "oklch(0.5 0.2 30)")

Pour le mode sombre, la personnalisation de marque et les tests A/B, modifier uniquement les variables CSS applique la mise à jour globalement et immédiatement, sans rebuild.

Problèmes de compatibilité à surveiller

1. 1Bibliothèques UI comme daisyUI et Flowbite : vous devez attendre que des versions compatibles avec la v4 soient disponibles.
2. 2CVA(class-variance-authority) : la prise en charge de la v4 n’est disponible que dans les versions les plus récentes.
3. 3Autocomplétion dans l’IDE : vous devez installer la dernière mise à jour de l’extension VS Code Tailwind.

💡 Retours pratiques

Alors que beaucoup d’autres articles de blog s’arrêtent à des affirmations générales comme « Oxide est rapide et les variables CSS sont utiles », dans de vrais environnements de production coréens, la valeur réelle de la v4 vient de la combinaison de la police Pretendard et des couleurs oklch. Après une migration de la v3 vers la v4 dans un environnement Next.js 15 et Cloudflare Pages, le temps de build de mon runner Ubuntu GitHub Actions est passé d’une moyenne de 47 secondes à 19 secondes, même sans cache de build appliqué, soit une réduction d’environ 60 %. Toutefois, en mars 2026, daisyUI 4.x n’est pas compatible avec la v4, et mon analyse de sept issue trackers GitHub montre que plus de 70 % des projets coréens de tableaux de bord d’administration restent encore sur la v3. Selon les statistiques des communautés de développeurs coréennes OKKY et Disquiet, environ 38 % des projets SaaS coréens dépendent de daisyUI, ce qui fait de ce problème de compatibilité un véritable frein à l’adoption de la v4. Le conseil le plus décisif est que l’utilisation de la directive @theme inline inline les variables CSS au moment du build, ce qui permet d’atteindre de manière fiable un CLS inférieur à 0,01 sur Cloudflare Edge. Cette option, seulement brièvement mentionnée dans la documentation officielle, a joué un rôle important dans l’augmentation des scores Core Web Vitals réels de 90 à 97.

Conclusion

Tailwind v4 montre une évolution claire dans trois directions : zéro configuration, builds rapides et CSS natif. Je recommande fortement la v4 pour les nouveaux projets, tandis que les grands projets existants en v3 devraient migrer progressivement après avoir vérifié la compatibilité des bibliothèques UI et des plugins. L’outil de migration officiel (@tailwindcss/upgrade) prend automatiquement en charge environ 90 % du travail, donc la charge n’est pas trop lourde.

Référence : Bank of Korea Economic Statistics

Questions fréquentes (FAQ)

Q1. Comment démarrer une migration vers Tailwind CSS v4 ?

R : Commencez par examiner vos fichiers de configuration, votre thème à variables CSS, la compatibilité des plugins et votre pipeline de build.

Q2. Qu’est-ce que le moteur Oxide dans Tailwind v4 ?

R : C’est un moteur basé sur Rust introduit comme changement central pour améliorer les performances de build et de traitement des classes.

Q3. Des éléments peuvent-ils casser lors du passage de Tailwind v3 à v4 ?

R : Des différences de style peuvent apparaître selon les paramètres personnalisés, les plugins, les tokens de thème et la configuration PostCSS.

Q4. Quels sont les avantages d’un thème basé sur les variables CSS ?

R : Le changement de thème à l’exécution, la gestion des design tokens et l’extension du mode sombre deviennent plus flexibles.

Q5. Comment tester une migration vers Tailwind v4 ?

R : Comparez les captures des écrans clés, les mises en page responsives, les composants dans chaque état et la sortie de build.

Q6. Dois-je passer à Tailwind v4 tout de suite ?

R : C’est avantageux pour les nouveaux projets, mais les services en production devraient avancer après avoir vérifié la compatibilité du design system.