Vérifier dans l’ordre :
- Le fichier CSS contient
@import "tailwindcss";.
- Ce fichier est importé par l’application (layout Astro,
main.jsx, layout.tsx).
- Le plugin est déclaré (
tailwindcss() dans vite.config/astro.config, ou @tailwindcss/postcss).
- Le serveur de développement a été redémarré après l’installation.
- Les outils de développement du navigateur montrent la classe appliquée dans l’onglet « Styles ».
npm ls tailwindcss @tailwindcss/vite
npm run build 2>&1 | head -30
| Cause |
Solution |
Nom construit dynamiquement ("bg-" + c) |
Écrire les noms complets, par exemple dans un objet |
| Fichier non détecté |
@source "../chemin"; dans le CSS |
| Classe supprimée ou renommée en v4 |
Voir Migration de la v3 à la v4 |
| Faute de frappe |
IntelliSense dans l’éditeur |
| Conflit avec une autre classe |
Une seule valeur par propriété ; tailwind-merge dans les composants |
| Spécificité d’un CSS tiers |
Placer le CSS tiers dans @layer, ou renforcer avec ! (!p-4) en dernier recours |
Classe dans un fichier ignoré par .gitignore |
Tailwind ignore ces fichiers : @source |
| Message |
Cause et solution |
Cannot find module '@tailwindcss/vite' |
npm install @tailwindcss/vite |
It looks like you're trying to use tailwindcss directly as a PostCSS plugin |
Utiliser @tailwindcss/postcss (ou le plugin Vite) |
Cannot apply unknown utility class |
Classe inexistante, ou @reference manquant dans un fichier séparé |
Unknown at rule @theme (éditeur) |
Extension CSS de l’éditeur : activer la prise en charge de Tailwind (IntelliSense) |
Can't resolve 'tailwindcss' |
Dépendance absente ou @import mal placé |
@import must precede all other statements |
Les @import doivent être au début du fichier CSS |
| Symptôme |
Piste |
dark: suit le système mais pas mon bouton |
Définir @custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *)); |
| Flash de thème clair au chargement |
Appliquer le thème dans un script du <head>, avant l’affichage |
| Un composant reste clair |
Couleurs codées en dur : utiliser des variables du thème (bg-fond) |
Voir Responsive et états.
| Symptôme |
Piste |
| La police n’est pas appliquée |
--font-sans du thème, fichier woff2 accessible, @import url() avant Tailwind |
| Scintillement à l’affichage de la police |
Précharger la police (<link rel="preload">), font-display: swap |
| Images qui débordent |
max-w-full h-auto |
| Contexte |
Point de vigilance |
| Astro |
Plugin dans vite.plugins, CSS importé dans le layout (voir Astro : dépannage) |
| Next.js |
postcss.config.mjs avec @tailwindcss/postcss, globals.css importé dans app/layout |
| Vite et React |
tailwindcss() dans plugins, index.css importé dans main.jsx |
| Markdown |
Classes prose du plugin Typography |
| Composants tiers |
@source vers leurs fichiers |
npx @tailwindcss/cli -i src/entree.css -o dist/style.css --minify
- Un CSS volumineux en développement est normal ; mesurer la version de production.
- Vérifier qu’aucune classe n’est construite dynamiquement en nombre.
- Servir le CSS compressé (
encode zstd gzip dans Caddy).
- Installer Tailwind CSS IntelliSense et ouvrir le projet à sa racine.
- Si la complétion échoue, vérifier que le fichier CSS principal est détecté (réglage
tailwindCSS.experimental.configFile).
- Mettre la prise en charge de
@theme, @utility, @custom-variant dans les paramètres CSS (css.lint.unknownAtRules: ignore).
Aucune propre à Tailwind. Sous Linux, la casse des noms de fichiers compte : vérifier les imports CSS.