Tailwind CSS v4 : Guide de migration et nouvelles fonctionnalités

Tailwind CSS v4 est la réécriture la plus importante depuis le lancement du framework. Le fichier de configuration JavaScript a disparu – remplacé par une configuration CSS d'abord utilisant des propriétés personnalisées. L'API de classe est en grande partie inchangée, mais les composants internes sont complètement nouveaux : un moteur basé sur Rust (oxide), une prise en charge de première classe de la gamme de couleurs P3, des requêtes de conteneur natives et un pipeline de construction qui s'intègre directement avec CSS plutôt que via les plugins PostCSS.

Ce guide vous explique ce qui a changé, pourquoi cela a changé et comment migrer une véritable application de production de Tailwind v3 vers v4. Nous aborderons les changements radicaux qui vous feront trébucher et les nouvelles fonctionnalités qui méritent d'être adoptées immédiatement.

Points clés à retenir

• tailwind.config.js est obsolète — la configuration est déplacée vers CSS à l'aide de la directive @theme
• L'importation est passée de @tailwind base/components/utilities à un seul @import "tailwindcss"
• Les couleurs personnalisées utilisent désormais les propriétés personnalisées CSS sous l'espace de noms --color-*
• La configuration content est automatique — Tailwind v4 analyse automatiquement les fichiers via glob
• Les requêtes de conteneur sont désormais intégrées avec les variantes @container et @sm:, @lg:
• Prise en charge de la gamme de couleurs P3 via l'espace colorimétrique oklch() pour toutes les couleurs intégrées
• @apply fonctionne toujours mais est moins nécessaire avec les propriétés personnalisées CSS
• Le moteur JIT est remplacé par Oxide (Rust) — compilation considérablement plus rapide

---

Qu'est-ce qui a changé et pourquoi

Tailwind v3 utilisait PostCSS comme pipeline de traitement, fichier de configuration JavaScript et générait des classes utilitaires via un moteur JIT écrit en JavaScript. Cela a bien fonctionné mais avait des limites :

• La configuration nécessitait JavaScript, le rendant inaccessible à partir des outils CSS uniquement
• Les propriétés personnalisées devaient être définies séparément de la configuration Tailwind
• Les requêtes de conteneur nécessitaient un plugin
• Le système couleur ne prend pas en charge la gamme P3

Tailwind v4 répond à tous ces problèmes en déplaçant la configuration dans CSS lui-même, en utilisant le système de propriétés personnalisées CSS natif du navigateur et en réécrivant le moteur dans Rust pour des versions 5 à 10 fois plus rapides.

---

##Installation

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

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

Le plugin @tailwindcss/vite s'intègre directement à Vite. Pour Next.js (qui utilise PostCSS en interne), utilisez @tailwindcss/postcss.

---

Configuration CSS-First

C’est le plus grand changement conceptuel. Votre globals.css devient la source de vérité pour la configuration Tailwind :

/* 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%);
}

Votre tailwind.config.js peut être supprimé (ou conservé pour l'instant — la v4 prend en charge les deux pendant la migration).

---

Détection de contenu

Tailwind v4 détecte automatiquement les fichiers modèles. La configuration content que vous aviez méticuleusement entretenue dans la v3 a disparu :

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

Dans la v4, Tailwind analyse automatiquement votre projet en utilisant des valeurs par défaut raisonnables. Si vous avez des fichiers dans des emplacements inhabituels, vous pouvez les inclure explicitement :

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

---

Mise à jour de la configuration postCSS

Pour les projets Next.js (et toute configuration basée sur PostCSS), mettez à jour votre configuration PostCSS :

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

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

autoprefixer est inclus dans @tailwindcss/postcss par défaut. Supprimez la dépendance autoprefixer distincte.

---

Système de couleurs : OKLCH

Tailwind v4 utilise OKLCH pour sa palette de couleurs intégrée. OKLCH est un espace colorimétrique perceptuellement uniforme : le réglage de la luminosité ressemble en fait à des étapes égales pour l'œil humain, contrairement au HSL.

/* 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);
}

Pour les écrans à gamme plus large (la plupart des téléphones et Mac modernes), OKLCH permet des couleurs que sRGB ne peut tout simplement pas représenter. Les valeurs oklch() sont automatiquement converties en rgb() pour les écrans qui ne prennent pas en charge P3.

---

Requêtes de conteneur – intégrées

Les requêtes de conteneur sont désormais de première classe dans la v4. Aucun plugin nécessaire :

/* 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>

Cela permet une réactivité au niveau des composants : une carte de barre latérale et une carte pleine largeur peuvent avoir des mises en page différentes sans CSS séparé.

Les conteneurs nommés vous permettent de cibler des ancêtres spécifiques :

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

---

Intégration des propriétés personnalisées CSS

Les propriétés personnalisées définies dans @theme sont accessibles partout : CSS, JavaScript et outils de conception qui lisent les variables CSS :

@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>

Cela remplace le modèle de maintien de valeurs parallèles dans tailwind.config.js et un fichier tokens.ts — il existe désormais une source unique de vérité en CSS.

---

Modifications radicales

1. Modifications de l'API du plugin

Les plugins v3 utilisant addBase, addComponents, addUtilities sont incompatibles avec la v4. Réécrivez-les au format CSS en utilisant le nouveau système de couches :

/* 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 avec classes personnalisées

@apply avec des classes non-Tailwind est plus restreint dans la v4. Utilisez @apply uniquement avec les classes utilitaires réelles :

/* 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 a disparu

La configuration dans JS n'est plus le chemin principal. Utilisez @theme en CSS. Si vous disposez des deux, la configuration CSS est prioritaire.

4. Nom de la palette de couleurs par défaut

Quelques noms de couleurs ont changé dans la v4. Exécutez le codemod officiel pour les attraper :

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

---

Stratégie migratoire

Pour une application de production volumineuse, migrez progressivement :

Phase 1 : Installation de la mise à jour

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

Mettre à jour postcss.config.mjs :

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

Mettre à jour globals.css :

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

Phase 2 : Exécutez le codemod

npx @tailwindcss/upgrade@next

Cela automatise la majeure partie de la migration : met à jour les noms de couleurs, convertit la configuration en CSS et signale les problèmes nécessitant une attention manuelle.

Phase 3 : Déplacer la configuration vers CSS

Prenez les valeurs de votre thème tailwind.config.js et déplacez-les vers @theme dans votre CSS. Supprimez le fichier de configuration après vérification.

Phase 4 : Adopter de nouvelles fonctionnalités

Remplacez les points d'arrêt réactifs basés sur la fenêtre d'affichage par des requêtes de conteneur, le cas échéant. Adoptez OKLCH pour les couleurs personnalisées afin d’obtenir la prise en charge de la gamme P3.

---

Améliorations des performances

Le moteur Oxide (Rust) de Tailwind v4 permet des builds nettement plus rapides :

Pour les applications volumineuses, cela se traduit par un développement HMR sensiblement plus rapide et des temps de création de CI nettement plus courts.

---

Exemple de migration dans le monde réel

Voici un avant/après pratique pour la configuration de base d'un système de conception :

// 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%);
}

La configuration native CSS est plus concise et élimine la dépendance node_modules pour la lecture de la configuration.

---

Questions fréquemment posées

Dois-je supprimer tailwind.config.js immédiatement ?

Non — Tailwind v4 prend en charge simultanément la configuration JS et la configuration CSS pendant la migration. La configuration JS fonctionne toujours, mais des fonctionnalités telles que @theme en CSS ne sont disponibles que sans elle. Migrez progressivement : commencez par créer l'application avec la v4, puis déplacez progressivement la configuration vers CSS, puis supprimez la configuration JS lorsque vous êtes confiant.

Mes classes Tailwind v3 existantes fonctionneront-elles toujours dans la v4 ?

La grande majorité des classes d'utilité sont inchangées. Certains noms de couleurs ont été mis à jour (gris → neutre dans certains contextes) et quelques utilitaires obsolètes ont été supprimés. Exécutez npx @tailwindcss/upgrade@next pour détecter automatiquement la plupart des problèmes. Les principales incompatibilités résident dans les plugins et la configuration des thèmes personnalisés, et non dans la façon dont vous utilisez les classes en HTML/JSX.

OKLCH est-il pris en charge dans tous les navigateurs ?

OKLCH est pris en charge dans tous les navigateurs modernes (Chrome 111+, Firefox 113+, Safari 15.4+). Tailwind v4 génère des solutions de secours pour les anciens navigateurs si nécessaire. Pour la gamme de couleurs P3 (les couleurs étendues), la prise en charge nécessite à la fois un affichage à large gamme et un navigateur compatible – Tailwind génère des solutions de repli rgb() pour les affichages à gamme plus étroite.

Comment utiliser Tailwind v4 avec shadcn/ui ?

shadcn/ui 2.0+ prend en charge Tailwind v4. Mettez à jour votre components.json pour utiliser le format de variables CSS v4. La bibliothèque de composants utilise des propriétés CSS personnalisées pour la thématique, qui correspondent naturellement au système @theme de Tailwind v4. Exécutez npx shadcn@latest init dans un projet existant pour obtenir la configuration compatible v4.

Existe-t-il des types TypeScript pour la nouvelle configuration ?

La configuration de Tailwind v4 est CSS, il n'y a donc pas de types TypeScript pour la configuration elle-même. La prise en charge de l'IDE provient des services de langage CSS qui comprennent les propriétés personnalisées. Pour accéder aux valeurs de thème dans TypeScript (pour les graphiques, les animations, etc.), utilisez getComputedStyle pour lire les propriétés personnalisées CSS au moment de l'exécution ou générez un fichier de jetons à partir de votre CSS dans le cadre de votre build.

---

Prochaines étapes

Tailwind CSS v4 est une mise à niveau importante qui mérite d'être adoptée pour les nouveaux projets et de planifier les projets existants. La pile frontale d'ECOSIRE exécute Tailwind CSS v4.1 en production sur une application Next.js 16 de 249 pages avec un système de conception complet.

Besoin d'aide pour une migration Tailwind v4 ou souhaitez-vous un système de conception construit à partir de zéro ? Découvrez nos services d'ingénierie front-end pour voir comment nous pouvons vous aider.