shadcn/ui Production Troubleshooting - Fix the Shit That Breaks

Your CI/CD just failed. Again. shadcn/ui builds fine locally but explodes in production. Here's what's actually breaking and how to fix it without losing your mind.

The Calendar IconLeft/IconRight TypeScript Nightmare

Error Message:

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

This specific bug hits randomly and will destroy your production build. The Calendar component's TypeScript definitions get out of sync with the actual props - happened to me when we were trying to ship some feature, I think it was late in the week.

Nuclear Fix:

## Delete and reinstall the component
rm -rf components/ui/calendar.tsx
npx shadcn@latest add calendar

Root Cause:

The react-day-picker types randomly break when they update their interfaces. Pretty sure this was around version 8.10 or something.

Production Prevention:

// package.json - Pin whatever version works for you
{
  "dependencies": {
    "react-day-picker": "8.10.1"  // Don't let this auto-update
  }
}

Next.js 15 + React 19 Build Explosions

Next.js 15 breaks half the shadcn/ui components due to React 19 changes. Your build will fail with cryptic errors about forwardRef and displayName.

What Breaks:

• Dialog components throw hydration errors
• Form components lose focus management
• Toast notifications disappear immediately
• Theme providers cause SSR mismatches

Working Fix:

Use Next 15, React 19, and whatever Radix versions don't explode. Check shadcn/ui's React 19 compatibility table before upgrading anything. Learned this the hard way after spending way too much time debugging hydration errors.

ESLint Version Hell

Error that appears:

Module not found: Can't resolve '@typescript-eslint/parser'

ESLint 9+ completely fucks up the CLI. Spent forever figuring out it was expecting the old config format or some shit.

ESLint versions that don't break everything:

Stay on ESLint 8.x for now. Don't upgrade to v9 until shadcn/ui catches up. I've seen this kill builds multiple times recently.

TypeScript Module Resolution Chaos

Error Message:

Cannot find module '@/components/ui/button' or its corresponding type declarations.

This happens when your tsconfig.json paths don't match what shadcn/ui expects.

Fix Your tsconfig.json:

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

The CLI assumes you're using @/ aliases. If you're not, either set them up or manually fix all the imports after adding components. This gotcha got me good.

Tailwind CSS Purge Issues

Your production build strips out necessary Tailwind classes, breaking component styling.

Problem:

Tailwind's purge process doesn't detect dynamically constructed classes in shadcn/ui components.

Fix - Update tailwind.config.js:

// Add your component paths and safelist the animation 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',
    // Add other animation classes as needed
  ]
}

Bundle Size Explosion

shadcn/ui + Tailwind can bloat your bundle to 2MB+ if you're not careful.

Bundle Analysis:

## See what's actually in your bundle
npx @next/bundle-analyzer

Bundle Optimizations:

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

Remove Unused Icons:

Don't import entire icon libraries. Use specific imports or you'll bundle everything.

Your bundle analyzer will show icon libraries taking up way too much space. Took me forever to realize all those icons were getting bundled. Fix the imports.

Hydration mismatches will kill your Next.js app in production. The server renders one thing, the client renders another, and React loses its shit. Here's what actually causes them and how to fix them without disabling SSR entirely.

Theme Provider Hydration Hell

Error Message:

Hydration failed because the initial UI does not match what was rendered on the server.

The most common shadcn/ui hydration error comes from the ThemeProvider component. Server renders in light mode, client mounts in dark mode, React explodes.

Root Cause: next-themes tries to read localStorage during SSR, which doesn't exist on the server.

Working Fix - Suppress Hydration Warnings:

// app/layout.tsx
import { ThemeProvider } from '@/components/theme-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider
          attribute="class"
          defaultTheme="system"
          enableSystem
          disableTransitionOnChange
        >
          {children}
        </ThemeProvider>
      </body>
    </html>
  )
}

The suppressHydrationWarning on the html tag prevents the theme mismatch error. It's not elegant, but it's the only solution that actually works.

Dialog Component Hydration Failures

Error: Dialog components render closed on server, open on client.

Problem: useState and useEffect cause server/client mismatches.

Fix - Dynamic Import with No SSR:

// components/dialog-wrapper.tsx
import dynamic from 'next/dynamic'

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

export { Dialog }

This prevents the dialog from rendering on the server at all. You lose SSR benefits but gain working components.

Form Components Lose Focus

Issue: Input fields lose focus after hydration, making forms unusable.

Cause: React can't match server-rendered id attributes with client-generated ones.

Fix - Stable IDs:

// components/ui/form-field.tsx
import { useId } from 'react'

export function FormField({ children }) {
  // Use React's useId for stable server/client IDs
  const id = useId()
  
  return (
    <div>
      <label htmlFor={id}>Name</label>
      <input id={id} name="name" />
    </div>
  )
}

useId() generates the same ID on server and client, preventing hydration mismatches.

Toast Notifications Disappear

Problem: Toasts show on server render, disappear immediately after hydration.

Fix - Client-Only Toasts:

// components/toast-wrapper.tsx
'use client'

import { useEffect, useState } from 'react'
import { Toaster } from '@/components/ui/toast'

export function ToastWrapper() {
  const [mounted, setMounted] = useState(false)
  
  useEffect(() => {
    setMounted(true)
  }, [])
  
  if (!mounted) return null
  
  return <Toaster />
}

Only render toasts after the client has mounted. No server/client mismatch possible.

Next.js 15 Hydration Breaking Changes

Next.js 15 made hydration stricter. Components that worked in 14.x now throw hydration errors.

Specific Breaking Changes:

• use client components are hydrated earlier
• Suspense boundaries behave differently
• React 19's concurrent features cause timing issues

Working Next.js 15 Setup:

// next.config.js
module.exports = {
  reactStrictMode: false, // Disable for shadcn/ui compatibility
  experimental: {
    ppr: false, // Partial prerendering breaks dialogs
  }
}

React Strict Mode + shadcn/ui = guaranteed hydration hell. Just turn the damn thing off.

Component State Persistence Issues

Error: Component state resets after hydration.

Problem: Server and client render different initial states.

Fix - Persistent State Pattern:

'use client'

import { useState, useEffect } from 'react'

export function StatefulComponent() {
  const [state, setState] = useState(() => {
    // Only access localStorage after mount
    if (typeof window === 'undefined') return defaultState
    return localStorage.getItem('key') || defaultState
  })
  
  useEffect(() => {
    // Sync state after hydration
    const saved = localStorage.getItem('key')
    if (saved && saved !== state) {
      setState(saved)
    }n  }, [])
  
  return <div>{state}</div>
}

This pattern ensures server renders the default state, then updates the client state after hydration completes.

The Nuclear Option - Disable SSR

When all else fails and you need to ship:

// components/client-only.tsx
import dynamic from 'next/dynamic'

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

// Usage - wrap problematic components
<ClientOnly>
  <ProblematicShadcnComponent />
</ClientOnly>

You lose SEO benefits and initial load performance, but your app actually works. Sometimes that's more important than perfect SSR. Used this to fix a checkout flow that was completely broken - everything else we tried just made it worse.