Why does my build fail with "IconLeft does not exist" in Calendar?

This is the [most reported shadcn/ui bug](https://github.com/shadcn-ui/ui/issues/5600). The Calendar component's TypeScript types get out of sync with react-day-picker updates.```bash# Nuclear option that always worksrm components/ui/calendar.tsxnpx shadcn@latest add calendar```Pin `react-day-picker` to whatever version works in your package.json to prevent this from happening again.

My CLI commands stopped working after upgrading Node.js

The shadcn CLI breaks with Node.js 20+ and npm 10+. You'll get certificate errors or module resolution failures.```bash# Check your versions first - use Node 18 if possiblenode --versionnpm --version# Fix certificate issuesnpm config set strict-ssl falsenpx shadcn@latest add buttonnpm config set strict-ssl true```

Build works locally but fails in Docker/CI

Your local Node.js version differs from production. Most CI systems use Node 20+, but shadcn/ui works best with Node 18.```dockerfile# Dockerfile - Use Node 18FROM node:18-alpine# Rest of your build``````yaml# GitHub Actions - Pin Node version- uses: actions/setup-node@v4 with: node-version: '18.x'```

TypeScript can't find my components after adding them

Your import paths are fucked. The CLI assumes you use `@/` aliases but your project doesn't have them configured.```json// tsconfig.json - Add these paths{"compilerOptions": {"baseUrl": ".","paths": {"@/*": ["./src/*"]}}}```

Components work in dev but break in production build

Tailwind CSS is purging the classes shadcn/ui uses. Tailwind can't see the dynamically constructed class names, so it thinks they're unused and strips them out.Add this to your `tailwind.config.js`:```javascriptmodule.exports = { content: [ './src/**/*.{js,ts,jsx,tsx}', './components/**/*.{js,ts,jsx,tsx}', ], safelist: [ 'data-[state=open]:animate-in', 'data-[state=closed]:animate-out' ]}```

Why do my builds take 5+ minutes now?

You're importing entire icon libraries. The build process has to analyze thousands of unused icons.```typescript// Slow - imports entire libraryimport * as Icons from '@radix-ui/react-icons'// Fast - imports one iconimport { CheckIcon } from '@radix-ui/react-icons'```

My Dialog won't close in production but works in dev

Classic Next.js hydration issue. The Dialog state gets fucked during server/client handoff.```tsx// Quick fix - disable SSR for dialogsimport dynamic from 'next/dynamic'const Dialog = dynamic(() => import('@/components/ui/dialog'), { ssr: false })```

Theme switching causes white flash in production

The `ThemeProvider` reads `localStorage` which doesn't exist during SSR. This causes a theme mismatch.```tsx// app/layout.tsx - suppress the hydration warning {children} ```

Form inputs lose focus after page load

React can't match server-generated IDs with client IDs. Use `useId()` for stable identifiers.```tsximport { useId } from 'react'function FormField() { const id = useId() return }```

Toasts appear then immediately disappear

Toast state gets reset during hydration. Only render toasts after client mount.```ts'use client'import { useEffect, useState } from 'react'export function ToastProvider() { const [mounted, setMounted] = useState(false) useEffect(() => setMounted(true), []) return mounted ? : null}```

Components work in Next.js 14 but break in Next.js 15

React 19 + Next.js 15 changed hydration behavior. Turn off strict mode and partial prerendering.```javascript// next.config.jsmodule.exports = { reactStrictMode: false, experimental: { ppr: false }}```

Bundle size exploded after adding shadcn/ui components

You're importing entire icon libraries. Check your bundle analyzer and fix the imports.```bash# See what's bloating your bundlenpx @next/bundle-analyzer``````typescript// Bad - imports 500KB of iconsimport * as Icons from 'lucide-react'// Good - imports 2KBimport { CheckIcon } from 'lucide-react'}```

Components render fine but styling is broken in production

Tailwind CSS purged the classes shadcn/ui needs. Add the dynamic classes to your safelist.```javascript// tailwind.config.jsmodule.exports = { safelist: [ 'data-[state=open]:animate-in', 'data-[state=closed]:animate-out' ]}```

Currently viewing the AI version

Switch to human version

shadcn/ui Production Troubleshooting - AI Knowledge Base

Critical Production Failures

Calendar Component TypeScript Errors

Failure Mode: Type error: Object literal may only specify known properties, and 'IconLeft' does not exist in type 'Partial<CustomComponents>'

Frequency: Random occurrence with high impact
Root Cause: react-day-picker type definitions break on version updates (particularly v8.10+)
Consequence: Complete build failure preventing deployment
Time Investment: Can destroy production deploys if not caught

Resolution:

rm -rf components/ui/calendar.tsx
npx shadcn@latest add calendar

Prevention Configuration:

{
  "dependencies": {
    "react-day-picker": "8.10.1"
  }
}

Next.js 15 + React 19 Compatibility Failures

Breaking Components:

Dialog components → hydration errors
Form components → focus management loss
Toast notifications → immediate disappearance
Theme providers → SSR mismatches

Working Configuration:

// next.config.js
module.exports = {
  reactStrictMode: false,
  experimental: {
    ppr: false
  }
}

Decision Criteria: Use Next 15 + React 19 only if you need bleeding-edge features; stick with Next 14 for production stability

Build System Failures

ESLint Version Incompatibility

Failure Point: ESLint 9+ breaks shadcn/ui CLI

Error: Module not found: Can't resolve '@typescript-eslint/parser'
Production Impact: Build pipeline failures
Safe Version: ESLint 8.x (do not upgrade to v9 until compatibility confirmed)

TypeScript Module Resolution

Configuration Requirements:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
      "@/components/*": ["./src/components/*"],
      "@/lib/*": ["./src/lib/*"]
    },
    "moduleResolution": "node"
  }
}

Failure Consequence: Complete inability to import components with @/ aliases

Bundle Size Explosion Thresholds

Critical Warning: shadcn/ui + Tailwind can reach 2MB+ bundle size

Primary Cause: Full icon library imports
Performance Impact: Significant load time degradation

Bundle Optimization:

// next.config.js
module.exports = {
  experimental: {
    optimizePackageImports: ['lucide-react', '@radix-ui/react-icons']
  }
}

Hydration Error Resolution

Theme Provider SSR Mismatch

Root Cause: next-themes attempts localStorage access during SSR
Consequence: Complete UI hydration failure

Working Fix:

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

Dialog Component Client-Side Only Solution

When to Use: When dialog state persistence causes hydration failures

const Dialog = dynamic(
  () => import('@/components/ui/dialog').then(mod => mod.Dialog),
  {
    ssr: false,
    loading: () => <div className="animate-pulse h-10 bg-gray-200" />
  }
)

Trade-off: Lose SEO benefits but gain functional components

Form Focus Management Recovery

Problem: Input fields lose focus post-hydration
Solution: Use React's useId() for stable server/client ID matching

import { useId } from 'react'

export function FormField({ children }) {
  const id = useId()
  return (
    <div>
      <label htmlFor={id}>Name</label>
      <input id={id} name="name" />
    </div>
  )
}

CSS Production Failures

Tailwind Purge Configuration

Critical Setting: Prevent Tailwind from stripping dynamic classes

module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx,mdx}',
  ],
  safelist: [
    'data-[state=open]:animate-in',
    'data-[state=closed]:animate-out',
  ]
}

Failure Mode: Components render without styling in production builds

Environment-Specific Issues

Node.js Version Compatibility Matrix

Recommended: Node.js 18.x
Problematic: Node.js 20+ with npm 10+
CI/CD Impact: Build failures in Docker/GitHub Actions using newer Node versions

Docker Configuration:

FROM node:18-alpine

GitHub Actions Configuration:

- uses: actions/setup-node@v4
  with:
    node-version: '18.x'

CLI Certificate Failures

Workaround for Node 20+ SSL issues:

npm config set strict-ssl false
npx shadcn@latest add button
npm config set strict-ssl true

Performance Optimization Thresholds

Bundle Analysis Requirements

npx @next/bundle-analyzer

Icon Import Optimization

Performance Impact: 500KB+ reduction possible

// Inefficient - imports entire library
import * as Icons from '@radix-ui/react-icons'

// Efficient - imports single icon (~2KB)
import { CheckIcon } from '@radix-ui/react-icons'

Critical Decision Points

When to Disable SSR

Criteria:

Hydration errors persist after configuration fixes
Deployment deadlines require immediate functionality
Component state complexity exceeds SSR compatibility

Implementation:

const ClientOnly = dynamic(() => Promise.resolve(({ children }) => <>{children}</>), {
  ssr: false
})

Version Pinning Strategy

High-Risk Dependencies:

react-day-picker (pin to working version)
ESLint (stay on v8.x)
Next.js (evaluate 15.x carefully)

Framework Migration Considerations

Next.js 14 → 15 Migration Risks:

React 19 compatibility issues
Stricter hydration validation
Changed Suspense boundary behavior
Concurrent rendering timing changes

Emergency Debugging Workflow

Build Failure: Check Calendar component TypeScript errors first
Hydration Error: Verify ThemeProvider configuration
Styling Missing: Confirm Tailwind safelist includes dynamic classes
Bundle Size: Analyze icon imports with bundle analyzer
CI/CD Failure: Verify Node.js version consistency

Resource Requirements

Time Investment Estimates

Calendar TypeScript Fix: 15-30 minutes
Hydration Error Resolution: 1-3 hours depending on complexity
Bundle Optimization: 2-4 hours for comprehensive analysis
Next.js 15 Migration: 1-2 days with potential breaking changes

Expertise Requirements

Essential: Understanding of SSR/hydration concepts
Helpful: Experience with Tailwind CSS purging
Advanced: Knowledge of React 19 concurrent features for Next.15 migration

Operational Intelligence

Most Common Production Breaks (in order of frequency)

Calendar component TypeScript errors
Theme provider hydration mismatches
Tailwind CSS class purging
Bundle size from icon imports
Next.js version compatibility

Hidden Costs

Bundle analysis time: Often overlooked until performance issues surface
SSR debugging complexity: Can require significant React knowledge
CI/CD environment differences: Node version mismatches cause deployment failures

Community Support Quality

GitHub Issues: High quality, most production errors already documented
Official Docs: Good for basic setup, insufficient for production troubleshooting
Community Discussions: Essential for edge cases and real-world solutions

Useful Links for Further Investigation

Essential Debugging Resources

Link	Description
shadcn/ui GitHub Issues	Search existing issues before creating new ones. Most production errors are already reported.
shadcn/ui Discussions	Community troubleshooting and solutions. Good for edge cases not covered in docs.
React 19 Compatibility Guide	Essential reading if you're upgrading to Next.js 15. Shows what's broken and what works.
shadcn/ui CLI Documentation	CLI commands and configuration options. Useful when npx shadcn@latest add fails.
Next.js Hydration Troubleshooting	Official Next.js guide to fixing hydration mismatches. Essential for SSR issues.
Vite + shadcn/ui Path Configuration Issues	Common Vite path configuration problems and solutions.
Laravel + Inertia.js Integration	Setup guide for Laravel projects using shadcn/ui.
Radix UI GitHub Issues	Underlying component issues. Check here if shadcn/ui components behave unexpectedly.
Tailwind CSS Purging Documentation	How to prevent Tailwind from breaking your component styles in production.
next-themes Hydration Issues	Theme provider problems and server/client mismatches.
@next/bundle-analyzer	Shows exactly what's bloating your Next.js bundle.
webpack-bundle-analyzer	For non-Next.js projects. Visualizes bundle composition.
Bundle Phobia	Check the real size impact of shadcn/ui dependencies before adding them.
shadcn/ui Community Examples	Real developers sharing shadcn/ui production issues and solutions.
Stack Overflow shadcn-ui Tag	Specific error messages and their solutions.
Cursor Rules for shadcn/ui	Best practices and common patterns to avoid issues.

shadcn/ui Production Troubleshooting - AI Knowledge Base

Critical Production Failures

Calendar Component TypeScript Errors

Next.js 15 + React 19 Compatibility Failures

Build System Failures

ESLint Version Incompatibility

TypeScript Module Resolution

Bundle Size Explosion Thresholds

Hydration Error Resolution

Theme Provider SSR Mismatch

Dialog Component Client-Side Only Solution

Form Focus Management Recovery

CSS Production Failures

Tailwind Purge Configuration

Environment-Specific Issues

Node.js Version Compatibility Matrix

CLI Certificate Failures

Performance Optimization Thresholds

Bundle Analysis Requirements

Icon Import Optimization

Critical Decision Points

When to Disable SSR

Version Pinning Strategy

Framework Migration Considerations

Emergency Debugging Workflow

Resource Requirements

Time Investment Estimates

Expertise Requirements

Operational Intelligence

Most Common Production Breaks (in order of frequency)

Hidden Costs

Community Support Quality

Useful Links for Further Investigation

Essential Debugging Resources

Related Tools & Recommendations

Migrating CRA Tests from Jest to Vitest

Stop Stripe from Destroying Your Serverless Performance

Supabase + Next.js + Stripe: How to Actually Make This Work

Claude API + Next.js App Router: What Actually Works in Production

Migrate from Webpack to Vite Without Breaking Everything

Vite + React 19 + TypeScript + ESLint 9: Actually Fast Development (When It Works)

Remix - HTML Forms That Don't Suck

React Router v7 Production Disasters I've Fixed So You Don't Have To

Fix Astro Production Deployment Nightmares

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

Astro - Static Sites That Don't Suck

Thunder Client Migration Guide - Escape the Paywall

Fix Your Slow-Ass Laravel + MySQL Setup

Fix Prettier Format-on-Save and Common Failures

I've Been Using Tailwind + Headless UI + Next.js 15 for 8 Months - Here's the Brutal Truth

Headless UI - Components That Don't Look Like Ass

Get Alpaca Market Data Without the Connection Constantly Dying on You

Fix Uniswap v4 Hook Integration Issues - Debug Guide

How to Deploy Parallels Desktop Without Losing Your Shit

Fast React Alternatives That Don't Suck