Why does the shadcn CLI break with React 19?

React 19 support exists but the CLI still throws tantrums with peer dependency warnings.```bashnpx shadcn@latest init --legacy-peer-deps```The CLI will usually offer to add --legacy-peer-deps automatically, but not always.

TypeScript can't find my components

VS Code shows red squiggles on `@/components/ui/button` because TypeScript path mapping is fucked. This always breaks in Next.js 15 with the src directory enabled. I swear I've debugged this exact "Cannot find module '@/components/ui/button'" error more times than I can count.**Copy this tsconfig.json exactly:**```json{"compilerOptions": {"baseUrl": ".","paths": {"@/*": ["./src/*"]}}}```Then restart TypeScript: Cmd+Shift+P → "TypeScript: Restart TS Server"You'll do this 20 times. It's normal.

My button looks like unstyled HTML

This happens to everyone. Your components look like garbage because Tailwind isn't loading.**Check your globals.css:**```css/* This MUST be first in globals.css */@import "tailwindcss";```**Nuclear option (works 90% of the time):**```bashrm -rf .next && npm run dev```If that doesn't work, the CLI forgot to import globals.css in your root layout.

Dark mode breaks hydration

SSR and themes don't play nice. React complains because it can't guess what theme the user wants.**Just suppress the warning:**```tsx// app/layout.tsx {children} ```It's not elegant, but it works.

Can I use shadcn/ui with Bootstrap?

No. shadcn/ui needs Tailwind. You can't run both without everything breaking.If you have an existing Bootstrap project, you'll need to migrate section by section or start fresh.

How do I customize components?

Edit the component files directly. They're in `src/components/ui/`.Want a different button style? Open `button.tsx` and change the classes. That's the whole point - you own the code.

My icons aren't showing up

You probably forgot to install lucide-react or you're importing icons wrong.```bashnpm install lucide-react --legacy-peer-deps``````tsx// Right wayimport { Check, X } from "lucide-react"// Wrong wayimport Check from "lucide-react/check"```

Can I add shadcn/ui to an existing project?

Yes, but it's a pain. The CLI will try to overwrite your Tailwind config.Back up your existing config first. I learned this the hard way when the shadcn CLI overwrote my entire Tailwind config and I lost all my custom color palette:```bashcp tailwind.config.js tailwind.config.backup.jsnpx shadcn@latest init```Then manually merge your custom settings back in. Plan for 2-3 hours if you have custom colors, animations, or plugins. The CLI loves to nuke custom content sections.

Should I use App Router or Pages Router?

App Router. Pages Router works but App Router has better TypeScript support and you're less likely to run into weird SSR issues.

How do I update components?

You don't. You own the code now. If shadcn/ui releases an update, you manually copy any changes you want.There's an experimental `diff` command but it's not reliable yet.

Currently viewing the AI version

Switch to human version

shadcn/ui Next.js Setup: AI-Optimized Technical Reference

Critical Prerequisites

Required Versions:

Node.js 18.17+ (18.16 breaks on Windows with EACCES errors)
pnpm (npm causes dependency hell with React 19)
VS Code with TypeScript extension

Time Investment: 3 hours (not 30 minutes as docs claim)
Difficulty Level: Medium (higher than documentation suggests)

Configuration Settings That Work in Production

Project Creation

# Primary method
npx create-next-app@latest my-app --typescript --tailwind --app

# Fallback when network fails (60% of weird failures)
npm cache clean --force
pnpm create next-app my-app --typescript --tailwind --app

CLI Configuration Answers:

Turbopack: Yes (faster than Webpack)
Custom imports: No (breaks TypeScript path mapping)
ESLint: Yes (prevents runtime errors)

shadcn/ui Installation

# Standard installation
npx shadcn@latest init

# React 19 compatibility fix
npx shadcn@latest init --legacy-peer-deps

Critical CSS Import Order (globals.css):

/* MUST be first or components look like unstyled HTML */
@import "tailwindcss";

Breaking Points and Failure Modes

Common CLI Failures

Error Type	Frequency	Solution	Time Cost
Network timeouts	High	Clear npm cache, use pnpm	15 minutes
ENOTFOUND/EPERM	High	Nuclear reset (rm -rf)	30 minutes
Module not found	Very High	Restart TypeScript server	5 minutes
Port conflicts	Medium	Kill port 3000 processes	2 minutes

TypeScript Path Resolution Issues

Symptom: Red squiggles on @/components/ui/button
Root Cause: Next.js 15 + src directory breaks path mapping
Solution:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Recovery Action: Restart TypeScript server (done 20+ times per setup)

Dark Mode Hydration Problems

Critical Issue: White flash on every page load, wrong theme for 2 seconds
Production Impact: User complaints, accessibility issues (migraine triggers reported)
Solution:

<html lang="en" suppressHydrationWarning>
  <body>
    <ThemeProvider attribute="class" defaultTheme="system">
      {children}
    </ThemeProvider>
  </body>
</html>

Resource Requirements

Time Investments

Fresh setup: 3 hours (including debugging)
Existing project migration: 2-3 hours (with config backup/restore)
Component customization: Ongoing (you own the code)

Expertise Requirements

React/Next.js: Intermediate
TypeScript: Basic
Tailwind CSS: Basic
CSS path resolution debugging: Required

Breaking Changes and Migration Pain Points

React 19: Peer dependency warnings, requires --legacy-peer-deps
Next.js 15: Path mapping breaks with src directory
Bootstrap conflicts: Cannot coexist with shadcn/ui

Decision Criteria for Implementation Approaches

Method	Speed	Reliability	Complexity	Use Case
CLI Setup	Fast	Medium (Windows issues)	Low	New projects
Manual Copy-Paste	Slow	High	High	2 components max
Starter Templates	Instant	Medium	Low	Prototypes
Existing Migration	Very Slow	Low	Very High	Legacy projects

Production Gotchas Not in Documentation

Component Updates

Reality: No automated updates (you own the code)
Workaround: Manual diff comparison with upstream
Time Cost: 1-2 hours per major update

CSS Loading Order

Default Behavior: Components render as unstyled HTML
Root Cause: Tailwind imports after component styles
Impact: Professional UI looks like 1995 HTML

Windows Development Issues

Path Limit Problems: CLI fails on long Windows paths
Recommendation: Use WSL for development
Workaround Time: 2-4 hours setup

Critical Warnings

What Official Documentation Doesn't Tell You

CSS import order is critical - wrong order = unstyled components
TypeScript paths break frequently - plan for multiple restarts
Dark mode requires hydration suppression - not a clean SSR solution
React 19 support exists but CLI complains - always use legacy peer deps

Failure Recovery Procedures

# Nuclear option that fixes 90% of issues
rm -rf .next node_modules package-lock.json yarn.lock pnpm-lock.yaml
pnpm install
pnpm run dev

Port Conflict Resolution

# Kill process on port 3000
lsof -ti:3000 | xargs kill

Implementation Success Criteria

Verification Checklist

Next.js welcome page loads at localhost:3000
Button component has proper styling (not Times New Roman)
Dark mode toggle works without white flash
TypeScript imports resolve without red squiggles
VS Code autocomplete works for component props

Performance Thresholds

Dev server start: < 30 seconds (if longer, dependency issues)
Component styling load: Immediate (if delayed, CSS import order wrong)
Theme switching: < 100ms (if slower, SSR hydration issues)

Essential Dependencies

Required Packages

pnpm add next-themes --legacy-peer-deps  # Only dark mode solution that works with SSR
pnpm install lucide-react --legacy-peer-deps  # Icon library integration

VS Code Extensions (Critical)

bradlc.vscode-tailwindcss: Tailwind IntelliSense (mandatory)
dsznajder.es7-react-js-snippets: React snippets for productivity

Trade-offs Analysis

Benefits Worth the Setup Cost

Customizable components: Own the source code, unlimited modification
TypeScript integration: Full type safety with proper setup
Production-ready: Built on Radix UI (accessibility compliant)

Hidden Costs

Update maintenance: Manual process, no automated updates
Learning curve: Tailwind + Radix knowledge required
Debugging time: Path resolution and CSS ordering issues

Alternative Evaluation

vs Material-UI: More customizable but harder setup
vs Chakra UI: Better TypeScript support but steeper learning curve
vs Bootstrap: Cannot coexist, requires full migration

Community Support Quality

shadcn/ui GitHub Issues: High activity, responsive maintainer
Next.js Discord: Active community, faster than Stack Overflow
Documentation Quality: Good for happy path, lacks failure scenarios
Video Resources: 12-minute tutorial available (comprehensive, no fluff)

Useful Links for Further Investigation

Essential Resources (The Ones That Actually Matter)

Link	Description
shadcn/ui Installation Guide	The official docs. Read this first when the CLI shits the bed.
shadcn/ui GitHub Issues	Someone has already filed a bug for whatever broke. Search here before opening a new issue.
Next.js Discord Community	Active community that actually answers questions. Way better than Stack Overflow for Next.js stuff.
VS Code Tailwind CSS IntelliSense	Makes Tailwind actually usable. Autocomplete, linting, color previews. Install this or suffer. Extension ID: `bradlc.vscode-tailwindcss`
ES7+ React Snippets	Type "rfc" and get a React component. Saves you from typing boilerplate garbage all day. Extension ID: `dsznajder.es7-react-js-snippets`
shadcn/ui Examples	Real examples that actually work instead of toy demos. Copy these when you need inspiration.
Lucide React Icons	Icon library that actually works with shadcn/ui. Clean imports, consistent sizing.
Radix UI Documentation	The headless components shadcn/ui wraps. When shadcn components don't do what you want, go here.
next-themes GitHub	Dark mode that doesn't completely suck. Check issues here when theme switching breaks.

shadcn/ui Next.js Setup: AI-Optimized Technical Reference

Critical Prerequisites

Configuration Settings That Work in Production

Project Creation

shadcn/ui Installation

Breaking Points and Failure Modes

Common CLI Failures

TypeScript Path Resolution Issues

Dark Mode Hydration Problems

Resource Requirements

Time Investments

Expertise Requirements

Breaking Changes and Migration Pain Points

Decision Criteria for Implementation Approaches

Production Gotchas Not in Documentation

Component Updates

CSS Loading Order

Windows Development Issues

Critical Warnings

What Official Documentation Doesn't Tell You

Failure Recovery Procedures

Port Conflict Resolution

Implementation Success Criteria

Verification Checklist

Performance Thresholds

Essential Dependencies

Required Packages

VS Code Extensions (Critical)

Trade-offs Analysis

Benefits Worth the Setup Cost

Hidden Costs

Alternative Evaluation

Community Support Quality

Useful Links for Further Investigation

Essential Resources (The Ones That Actually Matter)

Related Tools & Recommendations

Vite vs Webpack vs Turbopack: Which One Doesn't Suck?

Migrating CRA Tests from Jest to Vitest

Build a Payment System That Actually Works (Most of the Time)

I Spent a Weekend Integrating Clerk + Supabase + Next.js (So You Don't Have To)

Deploy Next.js to Vercel Production Without Losing Your Shit

Radix UI - Headless React Components That Don't Suck

SvelteKit + TypeScript + Tailwind: What I Learned Building 3 Production Apps

SvelteKit - Web Apps That Actually Load Fast

Migrate from Webpack to Vite Without Breaking Everything

React Router - The Routing Library That Actually Works

React 앱 개느려서 유저들 다 튀는 거 막기

Migrate JavaScript to TypeScript Without Losing Your Mind

Deploy Next.js + Supabase + Stripe Without Breaking Everything

Remix - HTML Forms That Don't Suck

Remix vs SvelteKit vs Next.js: Which One Breaks Less

Astro - Static Sites That Don't Suck

Fix Astro Production Deployment Nightmares

Which Static Site Generator Won't Make You Hate Your Life

Anthropic TypeScript SDK

Webpack is Slow as Hell - Here Are the Tools That Actually Work