Get shadcn/ui Working with Next.js Without Losing Your Mind

The shadcn/ui docs make this look easy. It's fucking not. Here's what will go wrong and how to fix it without losing your mind.

What You Actually Need

The CLI randomly shits the bed, so you need backups:

• Node 18 or newer (18.17+ specifically - 18.16 breaks on Windows)
• pnpm (npm gives you dependency hell, trust me on this)
• VS Code with TypeScript extension (you'll restart it every 10 minutes)
• Coffee or whiskey (this will take 3 hours, not 30 minutes like the docs claim)

Check your setup:

node --version  # Needs to be 18.17+ - 18.16 throws EACCES errors
pnpm --version  # Get this or suffer through npm's broken peer deps

Make sure you have Node.js 18.17+. Yeah, the shadcn docs say 16 works, but I've debugged too many "Cannot resolve module" errors caused by Node 16's busted ESM handling. Get pnpm because npm's dependency resolution completely breaks with React 19 - you'll get peer dependency warnings that make no sense.

Creating the Next.js Project

create-next-app fails randomly. Network timeouts, registry errors, some bullshit about "permission denied" even when you're running as admin. No idea why. It just does.

Try this first:

npx create-next-app@latest my-app --typescript --tailwind --app

When that inevitably fails with ENOTFOUND or EPERM:

## Clear npm cache first - fixes 60% of weird failures
npm cache clean --force
pnpm create next-app my-app --typescript --tailwind --app

The CLI asks questions. Say yes to Turbopack (it's faster than Webpack). Say no to customizing imports (you'll break TypeScript path mapping). Say yes to ESLint unless you enjoy debugging runtime errors that a linter would catch.

If you get errors, nuke everything and start over. I've wasted entire afternoons trying to debug why create-next-app choked on a perfectly valid project name. rm -rf and starting over saves more time than reading Next.js issue threads where half the solutions don't work.

When Your Dev Server Won't Start

Your first npm run dev will probably shit itself with "Module not found" or "Unable to resolve dependency tree" errors.

Nuclear option that actually works:

cd my-app
rm -rf .next node_modules package-lock.json yarn.lock pnpm-lock.yaml
pnpm install
pnpm run dev

Go to http://localhost:3000. If you see the Next.js welcome page, you win. If you get a blank white screen or "This page could not be found", check the terminal - probably some TypeScript error about missing types.

Common failures I've seen:

• "Error: listen EADDRINUSE :::3000" - something's already running on port 3000, kill it with lsof -ti:3000 | xargs kill
• "Cannot find module 'next/font'" - you're using an old Next.js version, upgrade to 13.2+
• "Module parse failed" - usually Windows path separator bullshit, try WSL

Next step: Install shadcn/ui and watch it break in exciting new ways.

shadcn/ui is weird - instead of npm installing components, it downloads source code directly into your project. This is weird but it works great for customization, terrible for updates. The philosophy is "copy and paste" not "npm install and pray." It's built on Radix UI (solid headless components) and Tailwind (obviously) so you can actually customize things without wanting to quit programming.

Installing the CLI

cd my-app
npx shadcn@latest init

If you get React 19 peer dependency warnings or "ERESOLVE unable to resolve dependency tree":

npx shadcn@latest init --legacy-peer-deps

The CLI asks a bunch of questions. Just hit enter for everything unless you have strong opinions about color schemes. The defaults work fine. It'll ask about CSS variables vs Tailwind config - choose CSS variables unless you're already deep into Tailwind customization and don't want to change your setup.

When Your Components Look Like Garbage

Your first button will look like unstyled HTML. This is normal and infuriating.

Fix: Check your globals.css import order:

/* This MUST be first or everything breaks */
@import "tailwindcss";

I spent 2 hours debugging this exact issue because my button looked like plain HTML with Times New Roman font. Learn from my pain. This CSS import order issue catches everyone because the docs don't mention it prominently enough.

Installing Your First Components

Start with the basics that actually work:

npx shadcn@latest add button card input

Test it by creating a simple page to see if things are working. If your button looks like plain HTML with no styling, the CSS import is wrong.

Now you have components. Time to set up dark mode and watch it break in exciting new ways.

Dark mode seems simple until you try it. Your app flashes white on every page load, shows the wrong theme for 2 seconds, works perfectly in dev, completely breaks in production.

I deployed this once and got Slack messages at 2am from users complaining about white flashes. One guy said it triggered his migraine. Had to roll back the deployment and spent the next morning figuring out why SSR was serving light theme HTML but client-side JS was applying dark theme classes.

Installing next-themes

next-themes is the only one that actually works with SSR.

## React 19 breaks everything as usual
pnpm add next-themes --legacy-peer-deps

React 19 changed how peer dependencies work and now everything throws warnings. next-themes v0.3.0 technically supports React 19 but npm/pnpm still complain about peer deps. The --legacy-peer-deps flag shuts them up.

Fix the White Flash of Death

Your app flashes white on every load. Here's the fix that actually works:

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

The `suppressHydrationWarning` is basically giving up on proper SSR, but it works. React stops yelling "Warning: Text content did not match. Server: 'light' Client: 'dark'" in the console. This happens because the server doesn't know what theme the user wants, so it renders light theme, then the client JS kicks in and applies dark theme.

Add a Theme Toggle

Create a button that switches themes:

// components/theme-toggle.tsx
"use client"
import { useTheme } from "next-themes"
import { Button } from "@/components/ui/button"

export function ThemeToggle() {
  const { theme, setTheme } = useTheme()
  
  return (
    <Button onClick={() => setTheme(theme === "dark" ? "light" : "dark")}>
      Toggle Theme
    </Button>
  )
}

That's it. Dark mode is now working. Your components will adapt automatically if you used the shadcn/ui CSS setup correctly - basically Tailwind looks for a dark class on the <html> element and applies all the `dark:` variants.

Test it by creating a page with some buttons and toggling between themes. If the theme toggle button doesn't change appearance when you click it, your ThemeProvider probably isn't wrapping your content properly. Been there, done that.