shadcn/ui : dépannage des conflits de styles, composants qui ne s'affichent pas et erreurs de types

Vous fixez le composant Button à l’écran — il devrait être un joli bouton bleu, mais il ressemble à un simple bouton HTML, sans le moindre arrondi.

Au cours des trois derniers mois, j’ai piétiné plus de pièges que de lignes de code écrites. Conflits de styles, composants qui ne s’affichent pas, erreurs TypeScript — ces problèmes font presque partie des « spécialités » de shadcn/ui ; chaque nouveau projet en rencontre quelques-uns.

Aujourd’hui, je regroupe ces problèmes courants et leurs solutions, pour vous faire gagner du temps.

Dépannage des conflits de styles

Les conflits de styles sont le problème le plus fréquent, environ 40 % de tous les cas. Les causes principales :

Conflits de variables CSS

shadcn/ui utilise des variables CSS pour gérer les couleurs du thème. Elles sont définies dans globals.css :

:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
  --primary: 222.2 47.4% 11.2%;
  --primary-foreground: 210 40% 2%;
}

Le problème survient si votre projet a déjà sa propre configuration de thème, ou si vous avez modifié les couleurs Tailwind avant d’installer shadcn/ui — les deux configurations peuvent entrer en conflit.

Comment diagnostiquer ?

Ouvrez d’abord globals.css et vérifiez que toutes les variables CSS sont présentes. Puis contrôlez la configuration colors dans tailwind.config.js :

module.exports = {
  theme: {
    extend: {
      colors: {
        border: "hsl(var(--border))",
        input: "hsl(var(--input))",
        ring: "hsl(var(--ring))",
        background: "hsl(var(--background))",
        foreground: "hsl(var(--foreground))",
        primary: {
          DEFAULT: "hsl(var(--primary))",
          foreground: "hsl(var(--primary-foreground))",
        },
      },
    },
  },
}

Les deux côtés doivent correspondre. Une variable manquante fait échouer le style associé.

Mon expérience : avant d’installer shadcn/ui, sauvegardez tailwind.config.js et globals.css. Après l’installation, comparez les différences entre les deux fichiers et réintégrez manuellement la configuration écrasée.

Conflit entre Shadow DOM et Tailwind

Ce cas est intéressant. Le Shadow DOM sert à isoler les styles, mais les classes Tailwind ne traversent pas sa frontière.

Le scénario typique : le composant Dialog. DialogContent est rendu via un Portal dans document.body, donc hors du Shadow DOM — les styles disparaissent.

Deux solutions possibles :

Première option : ne pas utiliser le Shadow DOM :

const MyDialogWC = r2wc(MyDialog, {
  shadow: null  // désactiver le Shadow DOM
});

Le Portal fonctionne alors normalement, mais l’isolation des styles disparaît. Il faut gérer les styles globaux manuellement et faire attention aux conflits de noms de classes.

Deuxième option : utiliser Safelist pour forcer l’inclusion des classes :

// tailwind.config.js
module.exports = {
  safelist: [
    'bg-primary',
    'text-primary-foreground',
    'hover:bg-primary/90',
    'bg-red-500',
    'h-9',
    'h-10',
    'px-3',
    'px-4',
  ],
}

Cette approche garantit la génération des styles, mais Safelist augmente la taille du fichier CSS. Il faut trouver un équilibre.

Coexistence avec d’autres bibliothèques UI

Si votre projet utilise déjà MUI (Material-UI) et que vous souhaitez migrer vers shadcn/ui, vous rencontrerez des conflits de styles.

La cause : Preflight de Tailwind — il réinitialise les styles par défaut du navigateur. Les styles MUI sont aussi réinitialisés, ce qui affiche les composants de façon anormale.

Tentative courante :

Certains désactivent Preflight :

module.exports = {
  corePlugins: {
    preflight: false,  // désactiver Preflight
  },
}

Mais cela a un effet de bord : les styles Tailwind en pâtissent aussi. Certains composants peuvent s’afficher incorrectement.

Meilleure approche :

Alibaba Cloud - Choix n°1 des développeurs, 15 % de réduction exclusive sur Lighthouse

Obtenir -15 % →Pub

Utilisez la fonction prefix de Tailwind pour préfixer toutes les classes :

module.exports = {
  prefix: 'tw-',  // toutes les classes deviennent tw-bg-blue-500
}

Les classes Tailwind et MUI ne entrent plus en conflit. En revanche, il faut ajouter tw- manuellement devant chaque classe — un peu fastidieux.

Mon conseil : si le projet contient déjà beaucoup de composants MUI, ne migrez pas tout d’un coup. Utilisez d’abord le préfixe pour coexister : shadcn/ui pour les nouveaux composants, migration progressive des anciens.

Configuration Tailwind écrasée

Je suis tombé dans ce piège plusieurs fois.

Après npx shadcn-ui@latest init, le fichier de configuration Tailwind est écrasé. Surtout le tableau plugins — si vous aviez configuré @tailwindcss/forms ou d’autres plugins, ils disparaissent.

Les symptômes sont évidents : les champs de formulaire ont soudain un style bizarre, ou certains composants n’affichent plus aucun style.

Étapes de diagnostic :

1. Ouvrez la sauvegarde de tailwind.config.js d’avant l’installation
2. Comparez avec le fichier après installation
3. Réintégrez les plugins manquants :

module.exports = {
  // ... autres configurations
  plugins: [
    require("@tailwindcss/forms"),  // à remettre
    require("tailwindcss-animate"),
  ],
}

Prévention : sauvegardez les fichiers de configuration avant d’installer shadcn/ui. Ou utilisez un script dédié qui enregistre tous les plugins.

Dépannage des composants qui ne s’affichent pas

Les styles semblent corrects, mais le composant ne s’affiche pas du tout ? C’est aussi assez fréquent.

Erreur de configuration du chemin content

Tailwind doit savoir quels fichiers utilisent ses classes pour générer le CSS correspondant. Cette configuration se trouve dans le champ content de tailwind.config.js.

Le problème habituel : le répertoire des composants shadcn/ui n’est pas inclus.

Vérifiez la configuration :

module.exports = {
  content: [
    './src/app/**/*.{ts,tsx}',
    './src/components/**/*.{ts,tsx}',  // indispensable
    './app/**/*.{ts,tsx}',
    './pages/**/*.{ts,tsx}',
  ],
}

Si vos composants sont dans une bibliothèque UI sous node_modules, ajoutez aussi :

content: [
  // ... autres chemins
  './node_modules/@your-ui-lib/**/*.{ts,tsx}',
]

Mon expérience : à chaque nouveau répertoire de composants, pensez à l’ajouter à content. Sinon Tailwind ne scanne pas ces fichiers et les classes ne sont pas générées.

Problème de chemin globals.css

shadcn/ui a besoin d’un fichier CSS pour définir les variables de thème. Son chemin est configuré dans components.json.

Le problème vient souvent d’un chemin incorrect, ou de plusieurs fichiers globals.css.

Méthode de diagnostic :

Vérifiez d’abord components.json :

{
  "style": "default",
  "css": "src/app/globals.css",  // ce chemin
}

Puis confirmez :

1. Ce fichier existe-t-il vraiment ?
2. N’y a-t-il qu’un seul globals.css dans le projet ?
3. globals.css est-il correctement importé dans le fichier principal ?

S’il y a plusieurs globals.css, supprimez les doublons et ne gardez qu’un seul.

Vérification de l’import :

Dans un projet Next.js, globals.css doit être importé dans app/layout.tsx ou pages/_app.tsx :

import '@/app/globals.css'  // ou './globals.css'

Sans import, les variables CSS ne s’appliquent pas et tous les styles des composants disparaissent.

Variables CSS non définies

Parfois, globals.css existe, mais les variables ne sont pas définies.

Le cas typique : le mode sombre. Vous basculez en dark mode et les couleurs des composants sont incorrectes — souvent parce que les variables CSS du mode sombre ne sont pas configurées.

Vérifiez globals.css :

:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
}

.dark {
  --background: 222.2 84% 4.9%;
  --foreground: 210 40% 2%;
}

Les variables sous la classe .dark doivent être définies. Sinon, les composants en mode sombre n’ont pas de styles.

Cas particulier Tailwind v4 :

Avec Tailwind v4, la configuration diffère :

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
}

Ce mapping @theme inline est indispensable. Sans lui, Tailwind v4 ne reconnaît pas ces variables.

Problème de casse dans les chemins d’import

Je suis tombé dans ce piège deux fois.

Sous Windows, la casse des noms de fichiers n’est pas sensible ; sous Linux/Mac, si. Le développement local peut passer, mais le déploiement en production échoue.

Symptôme habituel : le composant s’affiche en local, mais le serveur signale un module introuvable après déploiement.

Railway - Plateforme de déploiement moderne, sans opérations complexes, en ligne en quelques minutes

Commencer →Pub

Erreur typique :

// ❌ incorrect : B majuscule dans Button
import { Button } from "@/components/ui/Button"

// ✅ correct : button en minuscules
import { Button } from "@/components/ui/button"

Les fichiers de composants shadcn/ui sont tous en minuscules. L’import doit utiliser un chemin en minuscules.

Méthode de diagnostic :

Vérifiez tous les imports de composants et assurez-vous que les chemins correspondent exactement aux noms de fichiers. Consultez surtout les messages d’erreur en production.

Dépannage des erreurs TypeScript

Les erreurs TypeScript sont moins fréquentes, mais tout aussi pénibles quand elles surviennent.

Erreur de type sur la propriété variant

Le composant Button de shadcn/ui a une propriété variant pour changer le style (default, destructive, outline, etc.).

Le message d’erreur ressemble souvent à :

Type '{ variant: string }' is not assignable to type 'IntrinsicAttributes & ButtonProps'.
Property 'variant' does not exist on type 'IntrinsicAttributes & ButtonProps'.

Cause :

Dans la définition de types du composant Button, la propriété variant n’est pas correctement exportée.

Méthode de diagnostic :

Ouvrez components/ui/button.tsx et vérifiez la définition de type de variant :

const buttonVariants = cva(
  "inline-flex items-center justify-center rounded-md text-sm font-medium",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground hover:bg-primary/90",
        destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
        outline: "border border-input bg-background hover:bg-accent hover:text-accent-foreground",
      },
    },
  }
)

interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {
  // VariantProps doit être présent ici
}

Si VariantProps<typeof buttonVariants> manque, le type de la propriété variant disparaît.

Mon expérience : face à cette erreur, vérifiez d’abord la définition de types du composant. Assurez-vous que VariantProps est correctement hérité.

Incompatibilité de version React

Avec React 19, si certaines dépendances ne le supportent pas encore, vous rencontrerez des erreurs de types.

Le message ressemble souvent à :

npm error ERESOLVE unable to resolve dependency tree
npm error Found: [email protected]

Deux solutions :

Première option, installation forcée :

npm install --legacy-peer-deps
# ou
npm install --force

Cela ignore les exigences de version des peer dependencies. Des problèmes de compatibilité restent possibles.

Deuxième option, rétrograder React :

npm install react@18 react-dom@18

Restez sur React 18 et attendez la mise à jour des dépendances avant de monter en version.

Mon conseil : pour un nouveau projet, React 18 est plus stable. Attendez que shadcn/ui et les autres dépendances supportent React 19 avant de migrer.

Problèmes de types avec React Hook Form

Le composant Form de shadcn/ui, utilisé avec React Hook Form et Zod, peut provoquer des problèmes de correspondance de types.

Le message ressemble souvent à :

Type 'info.${number}.fileName' is not assignable to type '"info" | "info.0" | "info.0.fileName"'

C’est un problème de types sur les champs de formulaire dynamiques. Le type du schéma Zod ne correspond pas au type de la propriété name de FormField.

Solution :

Assurez-vous que le type du schéma est correctement inféré :

const formSchema = z.object({
  email: z.string().email(),
  password: z.string(),
})

type FormValues = z.infer<typeof formSchema>  // cette inférence de type est indispensable

const form = useForm<FormValues>({
  resolver: zodResolver(formSchema),
})

La propriété name de FormField correspondra automatiquement aux noms de champs du schéma.

Mon expérience : les formulaires dynamiques (par exemple avec useFieldArray) ont des types plus complexes. Vérifiez attentivement la définition du schéma Zod et l’inférence TypeScript.

Dépendances de types manquantes

Parfois, TypeScript signale une erreur parce que @types/react ou @types/react-dom n’est pas installé.

Le message peut être :

Could not find a declaration file for module 'react'

Solution :

Vultr - Serveur cloud NVMe haute performance, 32 emplacements mondiaux, déploiement Docker en un clic

Voir les tarifs →Pub

npm install -D @types/react @types/react-dom

Après l’installation, redémarrez le serveur TypeScript (dans VSCode : Ctrl+Shift+P, puis « TypeScript: Restart TS Server »).

Prévention : installez les dépendances de types dès le début d’un nouveau projet. N’attendez pas l’erreur pour le faire.

Bonnes pratiques et mesures préventives

Après tous ces pièges, voici ce que j’en retiens.

Gestion des configurations

Sauvegardez les fichiers de configuration :

Avant chaque installation de shadcn/ui ou modification de la config Tailwind, sauvegardez :

cp tailwind.config.js tailwind.config.js.backup
cp globals.css globals.css.backup

Après l’installation, comparez les différences et fusionnez manuellement.

Un seul fichier de configuration :

Un projet, un seul tailwind.config.js et un seul globals.css. Évitez les doublons, source de conflits.

Chemins content complets :

La configuration content doit couvrir tous les répertoires de composants :

content: [
  './src/**/*.{ts,tsx}',        // wildcard pour couvrir tous les dossiers
  './app/**/*.{ts,tsx}',
  './pages/**/*.{ts,tsx}',
  './components/**/*.{ts,tsx}',
]

Gestion des versions de dépendances

Vérifiez les peerDependencies :

Avant d’installer une nouvelle dépendance, consultez ses peerDependencies :

npm info <package> peerDependencies

Si la dépendance exige React 18 et que votre projet utilise React 19, évaluez la compatibilité.

Mettez à jour régulièrement les dépendances de types :

npm update @types/react @types/react-dom

Gardez les déclarations de types synchronisées avec la version de React.

Stratégie de tests

Testez immédiatement après l’installation :

Une fois shadcn/ui installé, testez tout de suite les styles :

1. Créez une page simple avec quelques composants shadcn/ui
2. Vérifiez que les styles s’affichent correctement
3. Testez le basculement en mode sombre
4. Lancez la compilation TypeScript

Testez en environnement de production :

Le local qui fonctionne ne garantit pas la production :

npm run build
npm run preview

Prévisualisez après le build pour vérifier styles et types.

Résumé

En résumé, les problèmes courants de shadcn/ui se concentrent sur trois axes :

1. Conflits de styles : configuration écrasée, conflits de variables CSS, coexistence avec d’autres bibliothèques UI
2. Composants qui ne s’affichent pas : chemin content mal configuré, problème de chemin globals.css, sensibilité à la casse des imports
3. Erreurs TypeScript : type variant manquant, incompatibilité de version React, dépendances de types absentes

En cas de problème, suivez cet ordre :

1. Vérifiez d’abord les fichiers de configuration (tailwind.config.js, globals.css)
2. Puis les chemins (content, imports)
3. Enfin les définitions de types (types des composants, versions des dépendances)

Si vous débutez avec shadcn/ui, testez d’abord le flux complet sur un projet vierge. Une fois la configuration et les pièges courants maîtrisés, passez à un projet réel.

shadcn/ui est très utile, mais la configuration demande un peu d’attention. Avec ces méthodes de diagnostic, les problèmes deviennent beaucoup moins stressants.