Tailwind CSS v4 avec Laravel : installation, configuration CSS-first et migration depuis la v3

Tailwind CSS v4 est la version utilisée par les starter kits récents de Laravel, mais de nombreux projets tournent encore en v3. Cette version change surtout la manière de configurer Tailwind : le fichier tailwind.config.js laisse place à une configuration directement dans le CSS. Voici comment l'installer, la configurer et migrer un projet existant.

Ce qui change avec la v4

• Configuration CSS-first : le thème se déclare dans le CSS avec @theme.
• Détection automatique des fichiers : plus besoin de lister les chemins content dans la plupart des cas.
• Une seule ligne d'import : @import "tailwindcss"; remplace les trois directives @tailwind.
• Plugin Vite dédié : @tailwindcss/vite, plus rapide que la chaîne PostCSS.
• Variables CSS natives : chaque valeur du thème devient une variable CSS utilisable partout.
• Moteur réécrit, avec des compilations nettement plus rapides.

Installation sur un projet Laravel

npm install tailwindcss @tailwindcss/vite

Dans vite.config.js :

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
    plugins: [
        laravel({
            input: ['resources/css/app.css', 'resources/js/app.js'],
            refresh: true,
        }),
        tailwindcss(),
    ],
});

Dans resources/css/app.css :

@import "tailwindcss";

Il ne reste qu'à inclure les assets dans le layout avec @vite(['resources/css/app.css', 'resources/js/app.js']) et lancer npm run dev.

Configurer le thème avec @theme

@import "tailwindcss";

@theme {
    --font-sans: "Inter", ui-sans-serif, system-ui, sans-serif;
    --color-brand-500: #1d4ed8;
    --color-brand-600: #1e40af;
    --breakpoint-3xl: 1920px;
}

Ces variables génèrent les utilitaires correspondants (bg-brand-500, font-sans, 3xl:) et restent accessibles en CSS classique via var(--color-brand-500).

Indiquer des sources supplémentaires

La détection automatique ignore les fichiers listés dans .gitignore, comme vendor/. Si vous utilisez des vues de packages (pagination Laravel, composants Filament…), déclarez-les :

@source "../../vendor/laravel/framework/src/Illuminate/Pagination/resources/views/*.blade.php";

Migrer un projet depuis Tailwind v3

1. Créez une branche et vérifiez que le projet compile en v3.
2. Lancez l'outil officiel : npx @tailwindcss/upgrade. Il met à jour les dépendances, convertit la configuration en CSS et renomme une partie des classes dans vos templates.
3. Vérifiez le diff : l'outil ne voit pas tout, notamment les classes construites dynamiquement en PHP ou en JavaScript.
4. Contrôlez visuellement les pages clés : certaines valeurs par défaut ont changé (couleur des bordures, taille des ombres et arrondis renommées, par exemple shadow-sm devenu shadow-xs).
5. Testez les navigateurs cibles : la v4 s'appuie sur des fonctionnalités CSS modernes et vise les navigateurs récents. Si vous devez supporter de vieux navigateurs, restez en v3.

Des tests visuels automatisés avec Playwright (voir notre guide Playwright pour Laravel) permettent de repérer rapidement les régressions.

Les pièges fréquents

• Classes dynamiques : "bg-{{ $couleur }}-500" n'est pas détecté. Écrivez les classes complètes dans une table de correspondance.
• Plugins v3 : vérifiez leur compatibilité ; ils se chargent désormais avec @plugin dans le CSS.
• Ancien postcss.config.js à supprimer si vous passez au plugin Vite, pour éviter un double traitement.

Conclusion

Pour un nouveau projet Laravel, Tailwind v4 est le choix naturel : installation en deux fichiers, configuration dans le CSS et compilation rapide. Pour un projet existant, la migration est largement automatisée, mais prévoyez une demi-journée de vérification visuelle. Pour aller plus loin côté front, voir Laravel Wayfinder.