Installer et configurer Tailwind CSS v4 (Vite et CLI)

Vous ouvrez un projet front-end et la première friction arrive avant la première ligne de design : comment brancher Tailwind CSS proprement, sans empiler les fichiers de configuration ni vous tromper de version ? Depuis la version 4, sortie en janvier 2025 et arrivée à la 4.3 en mai 2026, l’installation a radicalement changé. Plus de tailwind.config.js obligatoire, plus de directives @tailwind : un plugin, une ligne de CSS, et le moteur compile en microsecondes. À la fin de ce tutoriel, vous aurez un projet Vite fonctionnel où Tailwind reconstruit votre feuille de styles à chaque frappe, et vous saurez configurer votre thème directement en CSS.

🎯 Ce que vous allez apprendre

• Initialiser un projet Vite et y intégrer Tailwind CSS v4 via le plugin officiel @tailwindcss/vite.
• Remplacer l’ancienne configuration JavaScript par la configuration CSS-first avec la directive @theme.
• Installer Tailwind de trois manières différentes : plugin Vite, CLI autonome, et plugin PostCSS — et savoir laquelle choisir.
• Vérifier que la compilation fonctionne et diagnostiquer les erreurs d’installation les plus courantes.

🛠️ Ce que vous allez construire

Tout au long de ces leçons, nous construisons StockLab, l’interface d’un tableau de bord de gestion d’inventaire : liste d’articles, fiches produit, indicateurs de stock. Aujourd’hui, on pose les fondations : un projet propre où la moindre classe utilitaire tapée dans le HTML apparaît instantanément à l’écran. Le résultat visible de cette première étape : un titre stylé « StockLab » qui change de couleur dès que vous modifiez votre thème.

Prérequis

• Node.js 20 ou supérieur (vérifiez avec node -v). Tailwind v4 fonctionne avec les versions LTS récentes.
• Un éditeur de code (VS Code recommandé, avec l’extension officielle Tailwind CSS IntelliSense).
• Notions de base de HTML et de la ligne de commande.
• Test express : si vous savez lancer npm install dans un dossier et ouvrir http://localhost dans le navigateur, vous êtes prêt.
• ⏱️ Temps estimé : environ 25 minutes.

Étape 1 — Créer le projet Vite

Avant Tailwind, il faut un outil qui sert les fichiers et recompile à la volée. Vite est aujourd’hui le standard pour les projets front-end : démarrage quasi instantané, rechargement à chaud, et un plugin Tailwind de première partie. On commence par échafauder un projet vanilla, sans framework, pour isoler ce que fait Tailwind.

npm create vite@latest stocklab -- --template vanilla
cd stocklab
npm install

La commande crée un dossier stocklab avec une structure minimale : index.html, main.js, style.css et un package.json. Le npm install télécharge les dépendances. Lancez npm run dev : vous devez voir une URL locale (généralement http://localhost:5173). Ouvrez-la, la page de démarrage Vite s’affiche. Si elle apparaît, votre socle est sain et on peut greffer Tailwind dessus.

✅ Point d’étape — Le serveur Vite tourne et la page par défaut s’affiche dans le navigateur. Pour vérifier : le terminal affiche « ready in … ms » et une URL. Si rien ne s’affiche, contrôlez votre version de Node avec node -v.

Étape 2 — Installer Tailwind CSS v4 et son plugin Vite

C’est ici que tout se joue. Tailwind v4 se branche sur Vite via un plugin dédié : il intercepte la compilation, scanne automatiquement vos fichiers pour détecter les classes utilisées, et génère uniquement le CSS nécessaire. Deux paquets suffisent.

npm install tailwindcss @tailwindcss/vite

Le paquet tailwindcss contient le moteur et les utilitaires ; @tailwindcss/vite est l’adaptateur qui connecte ce moteur au cycle de build de Vite. Contrairement à la v3, vous n’avez pas besoin d’installer postcss ni autoprefixer séparément : Tailwind v4 embarque Lightning CSS, qui gère le nesting, les préfixes vendeurs et le regroupement des imports pour vous.

Étape 3 — Déclarer le plugin dans la configuration Vite

Le plugin ne s’active pas tout seul : il faut le déclarer dans vite.config.js. Si ce fichier n’existe pas encore à la racine (le template vanilla n’en crée pas toujours), créez-le. Cette configuration indique à Vite d’exécuter Tailwind à chaque build.

// vite.config.js
import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [
    tailwindcss(),
  ],
})

On importe tailwindcss depuis le paquet @tailwindcss/vite, puis on l’ajoute au tableau plugins en l’appelant comme une fonction. C’est la totalité de la configuration de build : aucune option n’est obligatoire. Au prochain redémarrage du serveur, Vite chargera le plugin. Pensez à arrêter (Ctrl+C) puis relancer npm run dev pour que la nouvelle config soit prise en compte.

Étape 4 — Importer Tailwind dans votre CSS

Dernière pièce : dire à votre feuille de styles d’inclure Tailwind. En v3, on écrivait trois directives @tailwind base, @tailwind components et @tailwind utilities. En v4, une seule ligne remplace tout. Ouvrez style.css, videz son contenu de démonstration et mettez :

@import "tailwindcss";

Cette unique instruction injecte le reset moderne (Preflight), les variables de thème et le moteur d’utilitaires. Assurez-vous que ce style.css est bien importé dans votre main.js (la ligne import './style.css' doit être présente ; le template Vite l’ajoute par défaut). Sauvegardez : Vite recompile et la page change déjà d’apparence, car le reset Tailwind normalise les marges et les polices.

✅ Point d’étape — Tailwind est branché. Pour le prouver, remplacez le contenu du <body> de index.html par : <h1 class="text-4xl font-bold text-indigo-600">StockLab</h1>. Le titre doit apparaître grand, gras et indigo. Si la classe n’a aucun effet, la cause est presque toujours l’import CSS manquant dans main.js.

Étape 5 — Configurer le thème en CSS avec @theme

Voici le changement de paradigme de la v4 : la configuration vit désormais dans le CSS, pas dans un fichier JavaScript. La directive @theme déclare vos tokens de design — couleurs, polices, points de rupture — sous forme de variables CSS, et Tailwind en génère automatiquement les utilitaires correspondants. Définissons une couleur de marque pour StockLab.

@import "tailwindcss";

@theme {
  --color-stock-500: oklch(0.62 0.19 255);
  --color-stock-700: oklch(0.48 0.17 255);
  --font-display: "Inter", "sans-serif";
}

En déclarant --color-stock-500, vous créez d’un coup les utilitaires bg-stock-500, text-stock-500, border-stock-500, etc. Les couleurs sont ici exprimées en oklch(), l’espace colorimétrique moderne que Tailwind v4 privilégie pour des dégradés plus homogènes. Changez la classe du titre en text-stock-700 : il adopte instantanément votre bleu de marque. Vous tenez là le cœur de la philosophie v4 : une seule source de vérité, en CSS, partagée entre votre thème et vos utilitaires.

Étape 6 — Méthode alternative : le CLI autonome

Tous les projets n’utilisent pas un bundler. Pour une simple page statique, un site WordPress ou un prototype HTML, le CLI Tailwind compile votre CSS sans aucun outil de build. C’est la voie la plus légère. On installe le paquet CLI puis on lance la compilation en mode surveillance.

npm install tailwindcss @tailwindcss/cli
npx @tailwindcss/cli -i ./src/input.css -o ./src/output.css --watch

Le drapeau -i désigne le fichier d’entrée (celui qui contient @import "tailwindcss";), -o le fichier de sortie compilé, et --watch demande au CLI de recompiler à chaque modification. Il ne reste qu’à lier output.css dans le <head> de votre HTML avec une balise <link>. Cette approche est idéale quand vous intégrez Tailwind à un projet qui n’a pas d’écosystème Node élaboré.

Étape 7 — Méthode alternative : le plugin PostCSS

Si votre projet possède déjà une chaîne PostCSS (cas fréquent avec d’anciens setups, certains frameworks ou Webpack), Tailwind s’y intègre via un plugin PostCSS dédié. On installe @tailwindcss/postcss et on le déclare dans la configuration PostCSS.

npm install tailwindcss @tailwindcss/postcss

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

Important : en v4, le plugin PostCSS s’appelle @tailwindcss/postcss et non plus tailwindcss comme en v3. C’est une erreur de migration classique. Vous n’avez plus besoin de déclarer autoprefixer dans la liste : Tailwind gère les préfixes lui-même. Le reste — l’import CSS, le thème — reste identique aux autres méthodes.

Comprendre le choix entre les trois méthodes

La règle est simple. Si vous utilisez Vite (ou un framework qui repose dessus comme React Router, SvelteKit ou Nuxt), prenez le plugin Vite : c’est l’intégration la plus fluide et la plus rapide. Si vous travaillez sur une page statique ou un environnement sans bundler, le CLI autonome suffit. Le plugin PostCSS ne se justifie que si vous héritez d’une configuration PostCSS existante que vous ne pouvez pas retirer. Dans tous les cas, le moteur de compilation est le même : ce sont seulement trois portes d’entrée vers le même bâtiment.

Comprendre le moteur qui tourne sous le capot

Quand vous sauvegardez un fichier et que la page se met à jour avant même que vous ayez quitté l’éditeur des yeux, ce n’est pas de la magie : c’est le nouveau moteur de Tailwind v4, réécrit pour la vitesse. Les chiffres publiés par l’équipe sont éloquents : un build complet passe de 378 à 100 millisecondes, et une recompilation incrémentale sans nouveau CSS tombe à 192 microsecondes, soit près de 180 fois plus rapide qu’en v3. Concrètement, votre boucle de feedback devient instantanée : vous tapez une classe, vous la voyez. Cette réactivité change la manière de travailler ; on expérimente librement parce que l’attente a disparu.

Le second atout de ce moteur, c’est la détection automatique de contenu. En v3, il fallait maintenir un tableau content listant les fichiers à scanner ; un oubli, et une classe utilisée dans un nouveau composant n’était jamais générée. En v4, Tailwind découvre seul vos fichiers de templates en s’appuyant sur des heuristiques : il ignore ce qui se trouve dans .gitignore, écarte les binaires et les fichiers CSS, et parcourt le reste. Pour StockLab, cela signifie que vous pouvez créer de nouveaux fragments HTML sans jamais toucher à la configuration : les utilitaires qu’ils contiennent apparaîtront dans le CSS compilé. Si vous avez un cas particulier — un dossier hors arborescence à scanner ou, au contraire, à exclure — la directive @source permet de l’ajouter ou de le retirer explicitement.

Compiler pour la production

Le mode développement génère un CSS confortable à déboguer, mais ce n’est pas ce que vous livrez aux visiteurs. Pour la mise en ligne de StockLab, vous produisez une version optimisée : minifiée, débarrassée de tout ce qui ne sert pas. Avec Vite, une seule commande s’en charge.

npm run build

Cette commande crée un dossier dist/ contenant votre HTML, votre JavaScript et un CSS final où ne subsistent que les utilitaires réellement employés dans vos fichiers. C’est l’un des grands atouts de l’approche utilitaire : au lieu de livrer une feuille de styles monolithique de plusieurs centaines de kilo-octets, vous n’expédiez que le strict nécessaire, souvent quelques kilo-octets une fois compressé. Vérifiez le poids du fichier généré dans dist/assets/ : il doit rester modeste même quand votre interface s’étoffe, parce que deux composants qui réutilisent flex et p-4 ne dupliquent jamais ces règles. Plus votre projet grandit, plus cet avantage se confirme : le CSS croît bien plus lentement que le nombre d’écrans.

Un dernier réflexe utile : prévisualisez le build avant de le déployer avec npm run preview, qui sert le dossier dist/ exactement comme un hébergeur le ferait. Vous y détectez les surprises — une classe générée dynamiquement et donc non détectée, par exemple — avant qu’elles n’atteignent vos utilisateurs.

🐞 Pièges fréquents

✅ Récapitulatif

Vous venez de monter de zéro un projet Tailwind CSS v4 opérationnel. Vous avez échafaudé un projet Vite, installé les deux paquets, déclaré le plugin, importé Tailwind en une ligne, puis défini une couleur de marque directement en CSS avec @theme. Vous connaissez aussi les deux voies alternatives — CLI autonome et PostCSS — et le critère pour choisir. La fondation de StockLab est posée : chaque utilitaire que vous taperez désormais se compilera en temps réel.

🧾 Aide-mémoire

💪 À vous de jouer

Ajoutez à votre bloc @theme une seconde teinte de marque, --color-stock-100 très claire, puis utilisez-la comme fond de page via bg-stock-100 sur le <body>. Objectif : vérifier que définir un token suffit à générer l’utilitaire.

@theme {
  --color-stock-100: oklch(0.96 0.02 255);
  --color-stock-500: oklch(0.62 0.19 255);
}
/* dans index.html */
<body class="bg-stock-100">…</body>

Tutoriels frères

• Tailwind CSS moderne : le parcours et la carte des leçons — concepts, méthode et vue d’ensemble.
• Tailwind utility-first et responsive — la méthode de pensée derrière les classes utilitaires.
• Dark mode et thèmes par tokens — pousser @theme jusqu’au mode sombre.

Ressources et références

• Documentation officielle — installation avec Vite
• Documentation officielle — CLI Tailwind
• Annonce officielle de Tailwind CSS v4.0
• Notes de version sur GitHub

FAQ

Q : Ai-je encore besoin d’un fichier tailwind.config.js en v4 ?
R : Non, il n’est plus obligatoire. La configuration se fait en CSS avec @theme. Vous pouvez toujours charger une config JavaScript via la directive @config si vous migrez un ancien projet, mais ce n’est pas la voie recommandée pour un projet neuf.

Q : Faut-il installer autoprefixer et postcss séparément ?
R : Non. Tailwind v4 embarque Lightning CSS, qui ajoute les préfixes vendeurs et gère le nesting automatiquement. Ces dépendances de la v3 ne sont plus nécessaires.

Q : Mon site doit supporter de vieux navigateurs, est-ce un problème ?
R : Oui, potentiellement. Tailwind v4 s’appuie sur @property et color-mix(), disponibles à partir de Safari 16.4, Chrome 111 et Firefox 128. Pour un public sur navigateurs anciens, restez sur la branche 3.4.

Q : Le plugin Vite scanne-t-il automatiquement mes fichiers ?
R : Oui. La détection de contenu est automatique en v4 : il n’y a plus besoin de déclarer un tableau content. Les fichiers de votre projet sont découverts tout seuls.