Tailwind in Next.js 16 — Wrong content Config Generated a 14MB CSS File

// ============================================
// CORRECT content configuration
// ============================================

import type { Config } from 'tailwindcss'

const config: Config = {
  // EXACT source directories — never use './**/*'
  content: [
    './app/**/*.{ts,tsx}',       // App router pages
    './components/**/*.{ts,tsx}', // Shared components
    './lib/**/*.{ts}',            // Utility functions with class names
    './src/**/*.{ts,tsx}',        // Any additional source directories
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

export default config

// ============================================
// WRONG — overbroad, scans node_modules
// ============================================

// Wrong: content: ['./**/*.{ts,tsx}']
// This matches:
//   - app/page.tsx ✓
//   - components/button.tsx ✓
//   - node_modules/package/node_modules/**/*.tsx ✗ — 500K+ extra files
//   - .next/build-manifest.json ✗
//
// Result: Tailwind finds millions of potential class combos
// CSS output: 14MB instead of 80KB

// ============================================
// Safelist for dynamic class names
// ============================================

const configWithSafelist: Config = {
  content: ['./app/**/*.{tsx}', './components/**/*.{tsx}'],
  safelist: [
    // Exact classes to always include
    'bg-red-500',
    'bg-green-500',
    'bg-blue-500',
    // Patterns: include all variants
    {
      pattern: /^bg-(red|green|blue)-(100|200|300|400|500)$/,
    },
    {
      pattern: /^text-(sm|md|lg|xl)$/,
    },
  ],
}

// ============================================
// CI check for CSS size
// ============================================

// Add to package.json or CI script:
// Check that the built CSS file is under 500KB
//
// #!/bin/bash
// CSS_SIZE=$(du -k .next/static/css/*.css | awk '{print $1}')
// if [ "$CSS_SIZE" -gt "500" ]; then
//   echo "FAIL: CSS file is ${CSS_SIZE}KB (limit: 500KB)"
//   exit 1
// fi
// echo "PASS: CSS file is ${CSS_SIZE}KB"

/* ============================================
   Component.module.css — colocated, scoped
   ============================================ */

.container {
  max-width: 1200px;
  margin: 0 auto;
  padding: 1rem;
}

.header {
  display: flex;
  justify-content: space-between;
  align-items: center;
  padding: 1rem 0;
  border-bottom: 1px solid #e5e7eb;
}

.grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
  gap: 1.5rem;
  padding: 2rem 0;
}

@media (max-width: 768px) {
  .grid {
    grid-template-columns: 1fr;
  }
}

// ============================================
// Component.tsx — importing CSS Module
// ============================================

// This works in BOTH Server and Client Components
import styles from './Component.module.css'

interface ProductGridProps {
  children: React.ReactNode
}

export function ProductGrid({ children }: ProductGridProps) {
  // styles.container and styles.grid are auto-generated unique class names
  // e.g., 'Component_container__3xY7a' and 'Component_grid__9kL2m'
  return (
    <div className={styles.container}>
      <header className={styles.header}>
        <h2 className="text-2xl font-bold">Products</h2>
        {/* Tailwind utility classes still work alongside CSS Modules */}
      </header>
      <div className={styles.grid}>
        {children}
      </div>
    </div>
  )
}

// ============================================
// Multiple class names with CSS Modules
// ============================================

import styles from './Card.module.css'
import clsx from 'clsx'

interface CardProps {
  variant: 'default' | 'featured' | 'compact'
  children: React.ReactNode
}

export function Card({ variant, children }: CardProps) {
  return (
    <div
      className={clsx(
        styles.card,
        variant === 'featured' && styles.featured,
        variant === 'compact' && styles.compact
      )}
    >
      {children}
    </div>
  )
}

/* ============================================
   app/globals.css — only imported in root layout
   ============================================ */

/* Tailwind directives — must be in a global CSS file */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* CSS reset — site-wide, applied once */
*,
*::before,
*::after {
  box-sizing: border-box;
  margin: 0;
  padding: 0;
}

/* Font face declarations — site-wide */
@font-face {
  font-family: 'Inter';
  src: url('/fonts/Inter-Variable.woff2') format('woff2');
  font-display: swap;
}

/* Custom properties — site-wide */
:root {
  --color-primary: #2563eb;
  --color-secondary: #7c3aed;
  --max-width: 1200px;
}

/* ============================================
   app/layout.tsx — only place for global CSS import
   ============================================ */

import './globals.css' // Only here!

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body className="font-sans antialiased">{children}</body>
    </html>
  )
}

// ============================================
// WRONG — this will throw a build error
// ============================================

// app/dashboard/page.tsx
// import './dashboard.css' // ERROR: Global CSS cannot be imported from components

// Use CSS Modules instead:
// import styles from './dashboard.module.css'

// ============================================
// CSS-in-JS in app router — limitations
// ============================================

// --- Server Component — CANNOT use CSS-in-JS ---

import { styled } from 'styled-components' // ERROR in Server Component

// styled-components uses React context, which requires 'use client'
// This component will throw at build time

// --- CORRECT: wrap in Client Component ---

'use client'

import styled from 'styled-components'

const StyledButton = styled.button`
  background-color: #2563eb;
  color: white;
  padding: 0.5rem 1rem;
  border-radius: 0.375rem;
  font-weight: 600;

  &:hover {
    background-color: #1d4ed8;
  }
`

interface ButtonProps {
  children: React.ReactNode
  onClick?: () => void
}

export function Button({ children, onClick }: ButtonProps) {
  return <StyledButton onClick={onClick}>{children}</StyledButton>
}

// --- Avoid hydration flash with dynamic import ---

// If the styled component triggers a hydration mismatch (FOUT),
// use next/dynamic with ssr: false to prevent SSR

import dynamic from 'next/dynamic'

const DynamicButton = dynamic(
  () => import('./styled-button').then((mod) => mod.Button),
  { ssr: false } // Renders on client only — no SSR, no hydration mismatch
)

// ============================================
// Better approach: Tailwind + CSS Modules
// ============================================

// Zero runtime cost, works in Server Components, no FOUT
// The same button in Tailwind:

interface TailwindButtonProps {
  children: React.ReactNode
  onClick?: () => void
  variant?: 'primary' | 'secondary'
}

export function TailwindButton({
  children,
  onClick,
  variant = 'primary',
}: TailwindButtonProps) {
  return (
    <button
      onClick={onClick}
      className={`
        rounded-md px-4 py-2 font-semibold transition-colors
        ${variant === 'primary'
          ? 'bg-blue-600 text-white hover:bg-blue-700'
          : 'bg-gray-200 text-gray-900 hover:bg-gray-300'
        }
      `}
    >
      {children}
    </button>
  )
}

// ============================================
// Default PostCSS Config (create-next-app)
// ============================================

/** @type {import('postcss-load-config').Config} */
const config = {
  plugins: {
    'postcss-import': {},     // Resolves @import in CSS files
    'tailwindcss': {},         // Generates Tailwind utility classes
    'autoprefixer': {},        // Adds vendor prefixes (-webkit-, -moz-)
  },
}

export default config

// ============================================
// Custom PostCSS — adding additional plugins
// ============================================

const configWithCustom = {
  plugins: {
    'postcss-import': {},
    'tailwindcss': {},
    'postcss-nesting': {},    // Adds native CSS nesting support
    'autoprefixer': {
      flexbox: 'no-2009',    // Skip old 2009 flexbox prefixes
      grid: 'autoplace',     // Enable grid autoplacement prefixes
    },
    // cssnano should run LAST — it minifies
    ...(process.env.NODE_ENV === 'production'
      ? { cssnano: { preset: 'default' } }
      : {}),
  },
}

// ============================================
// WRONG — plugin order matters!
// ============================================

const wrongConfig = {
  plugins: {
    'autoprefixer': {},       // WRONG order: autoprefixer runs first
    'tailwindcss': {},        // Tailwind runs second — generates classes AFTER prefixing
    'postcss-import': {},     // WRONG: @import resolution should be first
  },
}

// autoprefixer has nothing to prefix because Tailwind hasn't run yet
// postcss-import runs late — @import statements in CSS won't resolve correctly

// ============================================
// Checking if PostCSS is working
// ============================================

// Run build and check output:
// 1. In .next/static/css/, verify the CSS file contains expected classes
// 2. Check for vendor prefixed properties: -webkit-, -moz-
// 3. Verify no @import statements remain in output
//
// Command:
// grep -E '@import|-webkit-|-moz-' .next/static/css/*.css | head -10

// ============================================
// Without twMerge — class conflicts
// ============================================

interface BadButtonProps {
  variant?: 'primary' | 'secondary'
  size?: 'sm' | 'md' | 'lg'
  className?: string
  children: React.ReactNode
}

function BadButton({ variant = 'primary', size = 'md', className, children }: BadButtonProps) {
  // Both 'px-4 py-2' AND user's 'px-2 py-1' are in the string
  // CSS order determines which wins — unpredictable
  return (
    <button
      className={`px-4 py-2 rounded ${variant === 'primary' ? 'bg-blue-600' : 'bg-gray-200'} ${className || ''}`}
    >
      {children}
    </button>
  )
}

// Usage: BadButton className="px-2 py-1"
// Result: className="px-4 py-2 rounded bg-blue-600 px-2 py-1"
// Both px sizes are applied — CSS cascade determines the winner

// ============================================
// With clsx + twMerge — conflict resolution
// ============================================

import { clsx } from 'clsx'
import { twMerge } from 'tailwind-merge'

interface ButtonProps {
  variant?: 'primary' | 'secondary'
  size?: 'sm' | 'md' | 'lg'
  className?: string
  children: React.ReactNode
}

function Button({ variant = 'primary', size = 'md', className, children }: ButtonProps) {
  return (
    <button
      className={twMerge(
        // Base classes
        'rounded font-semibold transition-colors focus:outline-none focus:ring-2',
        // Size classes
        clsx({
          'px-3 py-1.5 text-sm': size === 'sm',
          'px-4 py-2 text-base': size === 'md',
          'px-6 py-3 text-lg': size === 'lg',
        }),
        // Variant classes
        clsx({
          'bg-blue-600 text-white hover:bg-blue-700': variant === 'primary',
          'bg-gray-200 text-gray-900 hover:bg-gray-300': variant === 'secondary',
        }),
        // Consumer classes — passed from parent
        className
      )}
    >
      {children}
    </button>
  )
}

// Usage: <Button size="lg" className="px-2 py-1">Click</Button>
// twMerge detects conflict between 'px-6 py-3' (lg) and 'px-2 py-1' (consumer)
// The consumer's 'px-2 py-1' wins — last conflicting class in the merge wins
// Result: className="rounded font-semibold ... px-2 py-1 text-lg bg-blue-600 ..."

// ============================================
// WRONG — Tailwind can't analyze dynamic classes
// ============================================

interface BadAlertProps {
  // Tailwind sees 'className={`alert-${severity}`}' — can't resolve
  severity: 'info' | 'warning' | 'error' | 'success'
  message: string
}

function BadAlert({ severity, message }: BadAlertProps) {
  return (
    <div className={`p-4 rounded-md text-white alert-${severity}`}>
      {/* alert-info, alert-warning, etc. — NOT GENERATED by Tailwind */}
      {message}
    </div>
  )
}

// ============================================
// CORRECT — complete class names with conditional
// ============================================

interface AlertProps {
  severity: 'info' | 'warning' | 'error' | 'success'
  message: string
}

function Alert({ severity, message }: AlertProps) {
  // Full class names in each case — Tailwind can analyze these
  const severityStyles = {
    info: 'bg-blue-100 text-blue-900 border-blue-400',
    warning: 'bg-yellow-100 text-yellow-900 border-yellow-400',
    error: 'bg-red-100 text-red-900 border-red-400',
    success: 'bg-green-100 text-green-900 border-green-400',
  }

  return (
    <div
      className={`p-4 rounded-md border ${severityStyles[severity]}`}
      role="alert"
    >
      {message}
    </div>
  )
}

// ============================================
// Alternative: clsx for conditional classes
// ============================================

import clsx from 'clsx'

function AlertClsx({ severity, message }: AlertProps) {
  return (
    <div
      className={clsx(
        'p-4 rounded-md border',
        severity === 'info' && 'bg-blue-100 text-blue-900 border-blue-400',
        severity === 'warning' && 'bg-yellow-100 text-yellow-900 border-yellow-400',
        severity === 'error' && 'bg-red-100 text-red-900 border-red-400',
        severity === 'success' && 'bg-green-100 text-green-900 border-green-400'
      )}
      role="alert"
    >
      {message}
    </div>
  )
}

// ============================================
// Alternative: safelist in tailwind.config.ts
// ============================================

// tailwind.config.ts
const config = {
  content: ['./app/**/*.{tsx}', './components/**/*.{tsx}'],
  safelist: [
    // Pattern-based safelist for dynamic severity classes
    {
      pattern: /^bg-(blue|yellow|red|green)-(100|200|300|400|500)$/,
      variants: ['hover', 'focus', 'active'],
    },
    {
      pattern: /^text-(blue|yellow|red|green)-(900|800|700)$/,
    },
    {
      pattern: /^border-(blue|yellow|red|green)-(400|500)$/,
    },
  ],
}

/* ============================================
   app/globals.css — theme definition
   ============================================ */

@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
  :root {
    /* Light theme */
    --color-primary: 37 99 235;      /* blue-600 */
    --color-primary-foreground: 255 255 255;
    --color-secondary: 124 58 237;   /* violet-600 */
    --color-bg: 255 255 255;
    --color-bg-secondary: 249 250 251;
    --color-text: 17 24 39;
    --color-text-secondary: 107 114 128;
    --color-border: 229 231 235;
    --color-success: 22 163 74;
    --color-warning: 234 179 8;
    --color-error: 220 38 38;
  }

  .dark {
    /* Dark theme */
    --color-primary: 96 165 250;     /* blue-400 */
    --color-primary-foreground: 0 0 0;
    --color-secondary: 167 139 250;  /* violet-400 */
    --color-bg: 17 24 39;
    --color-bg-secondary: 31 41 55;
    --color-text: 243 244 246;
    --color-text-secondary: 156 163 175;
    --color-border: 55 65 81;
    --color-success: 74 222 128;
    --color-warning: 250 204 21;
    --color-error: 248 113 113;
  }
}

/* ============================================
   tailwind.config.ts — variable mapping
   ============================================ */

const config = {
  content: ['./app/**/*.{tsx}', './components/**/*.{tsx}'],
  darkMode: 'class', // Toggle via className on <html>
  theme: {
    extend: {
      colors: {
        primary: {
          DEFAULT: 'rgb(var(--color-primary) / <alpha-value>)',
          foreground: 'rgb(var(--color-primary-foreground) / <alpha-value>)',
        },
        secondary: {
          DEFAULT: 'rgb(var(--color-secondary) / <alpha-value>)',
        },
        bg: {
          DEFAULT: 'rgb(var(--color-bg) / <alpha-value>)',
          secondary: 'rgb(var(--color-bg-secondary) / <alpha-value>)',
        },
        text: {
          DEFAULT: 'rgb(var(--color-text) / <alpha-value>)',
          secondary: 'rgb(var(--color-text-secondary) / <alpha-value>)',
        },
        border: 'rgb(var(--color-border) / <alpha-value>)',
        success: 'rgb(var(--color-success) / <alpha-value>)',
        warning: 'rgb(var(--color-warning) / <alpha-value>)',
        error: 'rgb(var(--color-error) / <alpha-value>)',
      },
    },
  },
}

// ============================================
// Usage in components
// ============================================

// No hardcoded hex values — all colors come from theme variables
// <div className="bg-bg text-text">
// <button className="bg-primary text-primary-foreground">
// <p className="text-text-secondary">
// <div className="dark:bg-bg-secondary">

// Toggle dark mode:
// document.documentElement.classList.toggle('dark')

// ============================================
// shadcn/ui — installed via CLI, no npm dependency
// ============================================

// npx shadcn@latest init
// npx shadcn@latest add button card alert dialog

// Components are copied to components/ui/ — fully editable
// No runtime library, no CSS injection — just Tailwind classes

// --- components/ui/button.tsx (generated by shadcn/ui) ---

'use client'

import * as React from 'react'
import { cva, type VariantProps } from 'class-variance-authority'
import { cn } from '@/lib/utils'

const buttonVariants = cva(
  'inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0',
  {
    variants: {
      variant: {
        default: 'bg-primary text-primary-foreground shadow hover:bg-primary/90',
        destructive: 'bg-destructive text-destructive-foreground shadow-sm hover:bg-destructive/90',
        outline: 'border border-input bg-background shadow-sm hover:bg-accent hover:text-accent-foreground',
        secondary: 'bg-secondary text-secondary-foreground shadow-sm hover:bg-secondary/80',
        ghost: 'hover:bg-accent hover:text-accent-foreground',
        link: 'text-primary underline-offset-4 hover:underline',
      },
      size: {
        default: 'h-9 px-4 py-2',
        sm: 'h-8 rounded-md px-3 text-xs',
        lg: 'h-10 rounded-md px-8',
        icon: 'h-9 w-9',
      },
    },
    defaultVariants: {
      variant: 'default',
      size: 'default',
    },
  }
)

export interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {}

export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
  ({ className, variant, size, ...props }, ref) => {
    return (
      <button
        className={cn(buttonVariants({ variant, size, className }))}
        ref={ref}
        {...props}
      />
    )
  }
)
Button.displayName = 'Button'

// ============================================
// daisyUI — Tailwind plugin, adds component classes
// ============================================

// tailwind.config.ts
const config = {
  content: ['./app/**/*.{tsx}', './components/**/*.{tsx}'],
  plugins: [require('daisyui')], // Adds .btn, .card, .alert, etc.
  // daisyUI adds ~20KB to CSS output
}

// Usage: <button className="btn btn-primary">Click</button>
// <div className="card shadow-xl">...</div>

// ============================================
// Benchmark: CSS sizes for different setups
// ============================================

// Minimal Tailwind (content site, 10-20 components):
//   50-80 KB — good
//
// Medium Tailwind (dashboard, 50-100 components, custom theme):
//   100-150 KB — good
//
// Large Tailwind (complex app, multiple themes, plugins):
//   150-300 KB — acceptable, review if > 200KB
//
// Bloated (overbroad content, node_modules scanned):
//   2-15 MB — CRITICAL, fix content config immediately

// ============================================
// Measure CSS size in CI
// ============================================

// scripts/check-css-size.sh
// #!/bin/bash
// set -e
//
// CSS_FILE=$(ls .next/static/css/*.css 2>/dev/null | head -1)
// if [ -z "$CSS_FILE" ]; then
//   echo "No CSS file found in .next/static/css/"
//   exit 1
// }
//
// SIZE=$(du -k "$CSS_FILE" | awk '{print $1}')
// LIMIT=500
//
// if [ "$SIZE" -gt "$LIMIT" ]; then
//   echo "FAIL: CSS file is ${SIZE}KB (limit: ${LIMIT}KB)"
//   echo "Check tailwind.config.ts content array for overbroad globs"
//   exit 1
// fi
//
// echo "PASS: CSS file is ${SIZE}KB (limit: ${LIMIT}KB)"

// ============================================
// Analyze which classes are consuming the most space
// ============================================

// # Generate a human-readable breakdown of CSS output
// npx next build
//
// # Count unique class definitions in output
// grep -oE '\.([a-zA-Z0-9_-]+)' .next/static/css/*.css | sort | wc -l
//
// # Find largest rule blocks (possible inefficiencies)
// grep -oE '\{[^}]+\}' .next/static/css/*.css |
//   awk '{ print length() " " $0 }' |
//   sort -rn |
//   head -10
//
// # Check for duplicate class patterns
// grep -oE '\.(\w+)' .next/static/css/*.css |
//   sort |
//   uniq -c |
//   sort -rn |
//   head -20