Tailwind CSS : migration de la v3 à la v4

Tailwind 4 est une réécriture : configuration en CSS, moteur plus rapide, quelques classes renommées. Un outil de migration automatise l’essentiel.

Procédure

git switch -c migration-tailwind-4          # travailler sur une branche
npx @tailwindcss/upgrade                    # Node.js 20 ou plus
git diff                                    # relire les modifications
npm run build

L’outil met à jour les dépendances, le fichier CSS, la configuration et les classes des fichiers sources. Toujours relire le diff et parcourir visuellement le site.

Changements principaux

Tailwind 3	Tailwind 4
`@tailwind base; @tailwind components; @tailwind utilities;`	`@import "tailwindcss";`
`tailwind.config.js`	`@theme { … }` dans le CSS (ou `@config` pour conserver l’ancien fichier)
Plugin PostCSS `tailwindcss`	`@tailwindcss/postcss`, ou mieux `@tailwindcss/vite`
`content: [...]`	Détection automatique (`@source` pour ajouter)
`plugins: [require('...')]`	`@plugin "…";`
`autoprefixer` et `postcss-import`	Intégrés

Utilitaires renommés ou supprimés

Ancien	Nouveau
`shadow-sm`	`shadow-xs`
`shadow`	`shadow-sm`
`drop-shadow-sm`, `drop-shadow`	`drop-shadow-xs`, `drop-shadow-sm`
`blur-sm`, `blur`	`blur-xs`, `blur-sm`
`rounded-sm`, `rounded`	`rounded-xs`, `rounded-sm`
`outline-none`	`outline-hidden`
`ring` (3 px)	`ring-3` (`ring` vaut 1 px)
`bg-opacity-50`, `text-opacity-50`	`bg-black/50`, `text-white/50`
`flex-shrink-`, `flex-grow-`	`shrink-`, `grow-`
`overflow-ellipsis`	`text-ellipsis`
`decoration-slice`	`box-decoration-slice`

Les classes *-opacity-* sont supprimées : utiliser la syntaxe couleur/opacité.

Valeurs par défaut modifiées

Sujet	Tailwind 3	Tailwind 4
Couleur de bordure (`border`)	`gray-200`	`currentColor`
Couleur de `ring`	bleu	`currentColor`
Couleur du texte indicatif (`placeholder`)	`gray-400`	La couleur courante à 50 %
Curseur des boutons	`pointer`	`default` (comme les navigateurs)
Largeur de `ring`	3 px	1 px

Après migration, ajouter explicitement les couleurs de bordure (border border-gray-200) et, si nécessaire, rétablir le curseur :

@layer base {
  button:not(:disabled),
  [role='button']:not(:disabled) {
    cursor: pointer;
  }
}

Thème : de `tailwind.config.js` à `@theme`

Avant :

module.exports = {
  theme: {
    extend: { colors: { marque: '#4f46e5' }, fontFamily: { titre: ['Inter'] } },
  },
};

Après :

@theme {
  --color-marque: #4f46e5;
  --font-titre: 'Inter', sans-serif;
}

Voir Thème et personnalisation.

Variantes

Tailwind 3	Tailwind 4
`dark:` par `darkMode: 'class'`	`@custom-variant dark (...)` dans le CSS
Ordre des variantes empilées : de droite à gauche (`first:*:pt-0`)	De gauche à droite (`*:first:pt-0`)
`hover:` actif sur écran tactile	Limité aux appareils avec survol

`@apply` dans des fichiers séparés

Les fichiers CSS ou les blocs <style> de composants qui utilisent @apply ou theme() doivent référencer le CSS principal :

@reference "../../styles/global.css";

.carte {
  @apply rounded-xl p-4;
}

Vérifications après migration

npm run build sans erreur ni avertissement.
Parcours visuel : bordures, ombres, anneaux de focus, arrondis.
Test sur les navigateurs ciblés.
Mode sombre et variantes personnalisées.
Plugins tiers : versions compatibles avec Tailwind 4.

Dépannage

Symptôme	Piste
Les styles disparaissent	`@import "tailwindcss";` manquant, plugin Vite ou PostCSS non remplacé
Bordures noires ou de la couleur du texte	Nouvelle valeur par défaut : indiquer la couleur
Ombres ou arrondis différents	Échelle renommée (voir tableau)
`Cannot apply unknown utility class`	`@reference` manquant dans le fichier
Le plugin tiers échoue	Version non compatible : le mettre à jour
`npx @tailwindcss/upgrade` refuse de s’exécuter	Node.js trop ancien, ou dépôt avec des modifications non enregistrées

Ubuntu 24.04 et 26.04 : différences à connaître

Aucune propre à Ubuntu : la migration dépend de Node.js (20 ou plus pour l’outil) et du projet.

Pour aller plus loin

Guide de migration
Suite : Dépannage