shadcn/ui Troubleshooting: Stilkonflikte, fehlende Komponenten, TypeScript-Fehler

Sie starren auf die Button-Komponente auf dem Bildschirm – eigentlich sollte es ein schöner blauer Button sein, sieht aber aus wie ein ganz normaler HTML-Button, ohne abgerundete Ecken.

In den letzten drei Monaten habe ich mehr Fallen als Code geschrieben. Stilkonflikte, fehlgeschlagene Komponenten-Renderings, TypeScript-Fehler – das sind quasi die „Spezialitäten” von shadcn/ui. In fast jedem neuen Projekt tauchen ein paar davon auf.

Heute fasse ich diese häufigen Probleme und Lösungen zusammen – damit Sie weniger Umwege machen müssen.

Stilkonflikte: Fehlersuche

Stilkonflikte sind das häufigste Problem – etwa 40 % aller Fälle. Die Hauptursachen:

CSS-Variablen-Konflikte

shadcn/ui nutzt CSS-Variablen für Theme-Farben. Diese stehen in 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%;
}

Das Problem: Wenn Ihr Projekt schon ein eigenes Theme hat oder Sie Tailwind-Farben vor der shadcn/ui-Installation angepasst haben, können die Konfigurationen kollidieren.

Wie prüfen?

Öffnen Sie globals.css und prüfen Sie, ob alle CSS-Variablen vorhanden sind. Dann die colors-Konfiguration in 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))",
        },
      },
    },
  },
}

Beide Seiten müssen zusammenpassen. Fehlt eine Variable, greift der zugehörige Style nicht.

Meine Erfahrung: Sichern Sie tailwind.config.js und globals.css vor der shadcn/ui-Installation. Nach der Installation Dateien vergleichen und überschriebene Einstellungen manuell zurückholen.

Shadow DOM und Tailwind

Interessanter Fall: Shadow DOM isoliert Styles – Tailwind-Klassen durchdringen die Shadow-DOM-Grenze nicht.

Typisch bei der Dialog-Komponente: DialogContent rendert per Portal in document.body – außerhalb des Shadow DOM – und die Styles fehlen.

Zwei Lösungsansätze:

Erstens, Shadow DOM weglassen:

const MyDialogWC = r2wc(MyDialog, {
  shadow: null  // Shadow DOM deaktivieren
});

Portal funktioniert dann, aber die Isolation entfällt. Globale Styles manuell steuern und auf Klassennamen-Konflikte achten.

Zweitens, Safelist für Klassen:

// 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',
  ],
}

Styles werden generiert, aber Safelist vergrößert die CSS-Datei – abwägen.

Koexistenz mit anderen UI-Bibliotheken

Nutzen Sie schon MUI (Material-UI) und wollen zu shadcn/ui migrieren, gibt es Stilkonflikte.

Ursache: Tailwinds Preflight setzt Browser-Defaults zurück – auch MUI-Styles, Komponenten wirken kaputt.

Häufiger Versuch: Preflight deaktivieren:

module.exports = {
  corePlugins: {
    preflight: false,  // Preflight deaktivieren
  },
}

Nebenwirkung: Tailwind-Styles leiden mit – manche Komponenten rendern falsch.

Besserer Ansatz: Tailwind-Prefix für alle Klassen:

Alibaba Cloud - Top-Wahl für Entwickler, exklusiv 15 % Rabatt auf Lighthouse-Server

15 % Rabatt sichern →Anzeige

module.exports = {
  prefix: 'tw-',  // Klassen werden tw-bg-blue-500
}

Tailwind- und MUI-Klassen kollidieren nicht. Sie müssen tw- vor jede Klasse setzen – etwas umständlich.

Mein Rat: Bei vielen MUI-Komponenten nicht alles auf einmal migrieren. Prefix-Koexistenz, neue Teile mit shadcn/ui, alte schrittweise anpassen.

Überschriebene Tailwind-Konfiguration

Den habe ich mehrfach erwischt.

Nach npx shadcn-ui@latest init wird die Tailwind-Konfiguration überschrieben – besonders das plugins-Array. Hatten Sie @tailwindcss/forms oder andere Plugins, sind sie weg.

Symptome: Formularfelder sehen plötzlich seltsam aus, manche Komponenten ohne Style.

Schritte:

1. Backup von tailwind.config.js vor der Installation öffnen
2. Mit der neuen Konfiguration vergleichen
3. Fehlende Plugins ergänzen:

module.exports = {
  // ... weitere Konfiguration
  plugins: [
    require("@tailwindcss/forms"),  // wieder hinzufügen
    require("tailwindcss-animate"),
  ],
}

Prävention: Vor shadcn/ui Konfiguration sichern oder ein Skript für alle Plugins führen.

Komponenten rendern nicht: Fehlersuche

Styles ok, Komponente unsichtbar? Auch häufig.

Falsche content-Pfade

Tailwind muss wissen, in welchen Dateien Klassen vorkommen – sonst kein CSS. Das steht in content in tailwind.config.js.

Typisch: Das shadcn/ui-Komponentenverzeichnis fehlt in content.

Konfiguration prüfen:

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

Liegen Komponenten in node_modules einer UI-Lib, ergänzen:

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

Meine Erfahrung: Bei jedem neuen Komponentenordner den Pfad in content eintragen – sonst scannt Tailwind nicht und generiert keine Klassen.

globals.css-Pfad

shadcn/ui braucht eine CSS-Datei für Theme-Variablen – Pfad in components.json.

Typisch: falscher Pfad oder mehrere globals.css.

Prüfen:

Zuerst components.json:

{
  "style": "default",
  "css": "src/app/globals.css",  // dieser Pfad
}

Dann:

1. Existiert die Datei?
2. Nur eine globals.css im Projekt?
3. Wird globals.css im Entry korrekt importiert?

Mehrere globals.css? Überflüssige löschen, eine behalten.

Import prüfen:

In Next.js sollte globals.css in app/layout.tsx oder pages/_app.tsx importiert werden:

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

Ohne Import greifen CSS-Variablen nicht – Komponenten verlieren den Style.

Undefinierte CSS-Variablen

globals.css existiert, Variablen fehlen trotzdem.

Typisch Dark Mode: nach Wechsel falsche Farben – Dark-Mode-Variablen fehlen.

globals.css prüfen:

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

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

Unter .dark müssen Variablen definiert sein – sonst kein Dark-Mode-Style.

Tailwind v4:

Andere Konfiguration:

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

@theme inline ist Pflicht – sonst erkennt Tailwind v4 die Variablen nicht.

Groß-/Kleinschreibung bei Import-Pfaden

Zweimal erwischt.

Windows: Dateinamen case-insensitive. Linux/Mac: sensitive. Lokal ok, Produktion bricht.

Symptom: lokal rendert, auf dem Server Modul nicht gefunden.

KiloClaw - Managed OpenClaw für Unternehmen: AI-Agent-Orchestrierung und smartes Modell-Routing

Jetzt starten →Anzeige

Typischer Fehler:

// ❌ Falsch: Button mit großem B
import { Button } from "@/components/ui/Button"

// ✅ Richtig: button kleingeschrieben
import { Button } from "@/components/ui/button"

shadcn/ui-Dateinamen sind kleingeschrieben – Import-Pfad auch.

Prüfen: Alle Import-Statements gegen Dateinamen – besonders Produktions-Fehlermeldungen.

TypeScript-Typfehler: Fehlersuche

Seltener, aber nervig.

variant-Typfehler

Die Button-Komponente hat variant (default, destructive, outline …).

Typische Meldung:

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

Ursache: variant ist in der Typdefinition der Button-Komponente nicht korrekt exportiert.

Prüfen:

components/ui/button.tsx öffnen:

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 muss hier stehen
}

Fehlt VariantProps<typeof buttonVariants>, fehlt der Typ für variant.

Meine Erfahrung: Bei solchen Fehlern zuerst die Komponenten-Typen prüfen – VariantProps muss vererbt sein.

React-Versions-Inkompatibilität

React 19, manche Dependencies noch nicht kompatibel – Typfehler.

Typische Meldung:

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

Zwei Wege:

Erstens, erzwungene Installation:

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

Peer-Dependency-Anforderungen werden ignoriert – mögliche Laufzeitprobleme.

Zweitens, React downgraden:

npm install react@18 react-dom@18

React 18 bis Dependencies nachziehen.

Mein Rat: Neue Projekte mit React 18 starten. Upgrade auf 19, wenn shadcn/ui und Dependencies bereit sind.

React Hook Form Typen

Form-Komponenten mit React Hook Form und Zod – Typ-Mapping-Probleme.

Typische Meldung:

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

Dynamische Formularfelder – Zod-Schema-Typ passt nicht zum name von FormField.

Lösung:

Schema-Typ korrekt ableiten:

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

type FormValues = z.infer<typeof formSchema>  // Typableitung nötig

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

name in FormField passt dann zu den Schema-Feldern.

Meine Erfahrung: Dynamische Formulare (z. B. mit useFieldArray) sind komplexer – Zod-Schema und TypeScript-Ableitung genau prüfen.

Fehlende Typ-Abhängigkeiten

Manchmal fehlen @types/react oder @types/react-dom.

Mögliche Meldung:

Could not find a declaration file for module 'react'

Lösung:

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

Danach TypeScript-Server neu starten (VSCode: Ctrl+Shift+P, „TypeScript: Restart TS Server”).

🔥 Verschwende keine Monate für ungenutzte Produkte! Teste deine SaaS-Nutzenversprechen mit Adsterra bei kleinem Budget →

Jetzt testen →Anzeige

Prävention: Typ-Pakete von Anfang an installieren – nicht erst nach dem ersten Fehler.

Best Practices und Prävention

Aus vielen Fallen – ein paar Regeln.

Konfigurations-Management

Konfiguration sichern:

Vor shadcn/ui-Installation oder Tailwind-Änderung:

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

Nach Installation Unterschiede vergleichen und manuell mergen.

Eine Konfigurationsdatei:

Pro Projekt ein tailwind.config.js, eine globals.css – mehrere Dateien erzeugen Konflikte.

Vollständige Pfade:

content muss alle Komponentenverzeichnisse abdecken:

content: [
  './src/**/*.{ts,tsx}',        // Wildcard für alle Verzeichnisse
  './app/**/*.{ts,tsx}',
  './pages/**/*.{ts,tsx}',
  './components/**/*.{ts,tsx}',
]

Dependency-Versionen

peerDependencies prüfen:

Vor neuer Abhängigkeit:

npm info <package> peerDependencies

Verlangt das Paket React 18, Sie nutzen React 19 – Kompatibilität bedenken.

Typ-Abhängigkeiten aktualisieren:

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

Typdeklarationen an React-Version anpassen.

Teststrategie

Direkt nach Installation testen:

Nach shadcn/ui-Setup sofort Styles prüfen:

1. Einfache Seite mit ein paar shadcn/ui-Komponenten
2. Styles sichtbar?
3. Dark-Mode-Wechsel
4. TypeScript-Build

Produktion testen:

Lokal ok heißt nicht Produktion ok:

npm run build
npm run preview

Nach Build Vorschau – Styles und Typen prüfen.

Fazit

Die häufigsten shadcn/ui-Probleme konzentrieren sich auf drei Bereiche:

1. Stilkonflikte: überschriebene Konfiguration, CSS-Variablen, Koexistenz mit anderen UI-Bibliotheken
2. Kein Rendering: falsche content-Pfade, globals.css-Pfad, Import-Groß-/Kleinschreibung
3. TypeScript-Fehler: fehlende variant-Typen, React-Version, fehlende @types-Pakete

Reihenfolge bei Problemen:

1. Konfigurationsdateien (tailwind.config.js, globals.css)
2. Pfade (content, Imports)
3. Typdefinitionen (Komponenten, Dependency-Versionen)

Neu bei shadcn/ui? Erst in einem leeren Projekt den Ablauf durchspielen. Dann in echten Projekten – mit weniger Überraschungen.

shadcn/ui ist stark, die Konfiguration braucht Aufmerksamkeit. Mit diesen Schritten bleiben Sie bei Problemen gelassen.