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

Look, I've shipped 3 real apps with this stack, not just hello-world demos. After 8 months of fixing production bugs at 2am, I can tell you exactly where this combo will save your ass and where it'll make you want to burn your laptop. Here's the shit nobody warns you about.

Why These Three Tools Don't Suck Together

Tailwind CSS keeps your CSS bundle under control. My production app sits around 12KB gzipped because unused classes actually get purged (unlike every other CSS framework that promises this but fails). JIT compilation is fast enough that you're not sitting there waiting for rebuilds. No more bikeshedding about naming conventions or file organization. But the IntelliSense extension crashes harder than my hopes and dreams. Autocomplete just stops working randomly and you're back to restarting VS Code. It's maddening.

Headless UI fixes the accessibility nightmare you've been ignoring. I used to write modals and dropdowns, test them with a mouse, ship them, then get bug reports about keyboard navigation being completely broken. With Headless UI, those 16 components just work - focus trapping, ARIA attributes, keyboard navigation, all the shit that takes hours to get right. But the TypeScript types lag behind releases, so you'll waste an hour debugging why your perfectly valid props are throwing type errors. Turns out you're using the old interface.

Next.js 15 doesn't actively sabotage your life (mostly). The App Router stopped throwing random hydration errors every other build. React Server Components actually keep server code out of your client bundle. File-based routing makes sense and middleware handles auth without ceremony. Turbopack builds are fast when it works, but it randomly decides to rebuild your entire app during demos because computers hate us. The React 19 integration adds cool features while breaking half your dependencies.

What Actually Breaks in Production

Week one with this stack is CSS hell. Tailwind's specificity is intentionally low, so every random component library you install will override your carefully crafted styles. Tailwind's preflight resets will break any third-party component that expects browser defaults. I spent 3 days debugging why a date picker looked like trash before realizing Tailwind's reset was nuking the styles. Solution: stop installing random components and build everything yourself. Fun.

Mobile Safari wants to watch your career burn. Headless UI modals break focus trapping on iOS - users tap frantically and can't close the modal, then leave 1-star reviews calling your app "broken". Got flooded with support emails about this disaster. The fix is preventScroll: false hidden in a GitHub discussion that took me forever to find. iOS Safari is more unreliable than a chocolate teapot.

Next.js builds fail randomly for sport. You're coding along fine, run npm run build, and suddenly get "Module not found" errors for files that definitely exist. I've learned to rm -rf .next before debugging anything else because this happens way too often. The build cache corruption is about as stable as a house of cards in a hurricane.

Production Reality Check

My biggest app hits around 50K users monthly. Bundle is roughly 180KB JS, maybe 12KB CSS. First paint is around 1.2 seconds on 3G (not the fantasy 800ms from marketing demos). Layout shift hovers around 0.08 because Tailwind loads instantly but images don't, obviously. Web Vitals stay green if you optimize images properly.

The accessibility actually works though. I run axe DevTools and get zero errors on forms and navigation. Screen readers don't completely break. Lighthouse gives me 95+ without custom ARIA markup. That alone justifies the TypeScript headaches.

Big companies use this stack because they have DevOps teams to babysit the build pipeline weirdness. You probably don't.

But first you have to survive the setup from hell. That's where most developers rage-quit and crawl back to Create React App with Material-UI.

I'm about to save you 6 hours of wanting to quit programming. Here's the setup process that actually happens, not the fantasy version from the docs.

The Setup That Actually Works

The official docs make it look easy. One clean command and you're done, right? Bullshit.

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

Here's what really happens:

1. "Node.js version not supported" - you're on 16, need 18+
2. Update Node, now npm throws permission errors everywhere
3. Google "fix npm permissions", try sudo, break everything worse
4. Reinstall Node via nvm, spend forever fixing PATH
5. Command finally runs, ESLint shits itself, everything's red squiggles

Here's the process that actually works (after way too many failed attempts):

## Need Node 18+ or this breaks  
node --version

## The command that works on attempt #4
npx create-next-app@latest my-app --typescript --tailwind --eslint --app --src-dir

## Install Headless UI and cross your fingers
npm install @headlessui/react @heroicons/react
npm install -D @tailwindcss/forms @tailwindcss/typography

## Fix TypeScript having a meltdown
npm install -D @types/node@latest

Configuration Chaos

Every tutorial shows a Tailwind config that doesn't work. The content patterns miss files, the theme gets bloated, and plugins break in creative ways. Here's the config that won't fuck you over:

import type { Config } from 'tailwindcss'

const config: Config = {
  content: [
    './src/**/*.{js,ts,jsx,tsx,mdx}', // Covers everything, don't overthink it
  ],
  theme: {
    extend: {
      colors: {
        brand: '#3b82f6', // Pick whatever, change later
      },
    },
  },
  plugins: [
    require('@tailwindcss/forms'), // Forms look like trash without this
    require('@tailwindcss/typography'), // If you have blog content
  ],
}
export default config

Next.js config reality check - experimental features are called experimental for good reasons:

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    // Turbopack breaks randomly, disable if weird stuff happens
    turbo: process.env.NODE_ENV === 'development',
  },
  images: {
    formats: ['image/webp'], // AVIF breaks on older stuff
  },
  // Without this webpack will explode randomly
  webpack: (config) => {
    config.externals.push('pino-pretty', 'lokijs', 'encoding')
    return config
  }
}

module.exports = nextConfig

Component Patterns That Don't Suck

Everyone copies Headless UI examples from the docs and wonders why they break in production. Here's the pattern that won't make you hate your life:

'use client'
import { Dialog, DialogPanel, DialogTitle } from '@headlessui/react'
import { XMarkIcon } from '@heroicons/react/24/outline'

interface ModalProps {
  isOpen: boolean
  onClose: () => void
  title: string
  children: React.ReactNode
}

export default function Modal({ isOpen, onClose, title, children }: ModalProps) {
  return (
    <Dialog 
      open={isOpen} 
      onClose={onClose} 
      className="relative z-50"
      // This stops mobile Safari from losing its shit
      __demoMode={false}
    >
      {/* Backdrop */}
      <div className="fixed inset-0 bg-black/30" aria-hidden="true" />
      
      {/* Modal */}
      <div className="fixed inset-0 flex w-screen items-center justify-center p-4">
        <DialogPanel className="mx-auto max-w-sm space-y-4 rounded-lg bg-white p-6 shadow-lg">
          <div className="flex items-center justify-between">
            <DialogTitle className="text-lg font-medium">{title}</DialogTitle>
            <button
              onClick={onClose}
              className="rounded-md p-1 hover:bg-gray-100"
              aria-label="Close modal"
            >
              <XMarkIcon className="h-5 w-5" />
            </button>
          </div>
          {children}
        </DialogPanel>
      </div>
    </Dialog>
  )
}

Server Components Reality

React Server Components are cool in theory, nightmare in practice. The rules make no sense, hydration breaks randomly, and import boundaries are invisible tripwires. Here's what will break:

• Any component that uses useState or useEffect needs 'use client'
• Headless UI components are ALL client-side
• Your beautiful server component becomes client-side as soon as you add a button

The strategy that works: fetch data on the server, make everything else client-side. Stop fighting the boundaries and just slap 'use client' on shit until it works.

What They Don't Tell You

Tailwind IntelliSense is essential and broken. Install it, then get used to restarting VS Code when autocomplete dies (every 2 hours like clockwork).

Build errors make no sense. Module not found: Can't resolve 'fs' means you're using Node APIs in client components. The error message won't tell you this. Here's the fix:

// This fixes most \"Module not found\" errors
if (typeof window === 'undefined') {
  // Server-side only code here
}

Mobile Safari bugs will ruin your weekend. Headless UI modals break on iOS and the fix is hidden in a GitHub issue from 2022:

<Dialog
  open={isOpen}
  onClose={onClose}
  // This fixes iOS focus issues
  initialFocus={undefined}
>

Time to get this shit working: 4-6 hours if you know what you're doing, 2-3 days if you're new to this pain. Block your calendar and maybe warn your teammates you'll be grumpy.

If you survive the setup, next comes the fun part: realizing you could have shipped your app weeks ago with Material-UI.