Downgrading from Tailwind CSS v4 to v3: A Hard-Earned Journey Back to Stability

"Sometimes progress means stepping back. Especially when the future breaks your layout."

Context

While upgrading our Next.js app to the latest Tailwind CSS v4, we encountered a host of styling issues, from custom classes not being applied, to broken layouts, font glitches, and unexpected build behavior.

After 48 hours of relentless debugging, we decided to rollback to Tailwind v3.3.5, and here's a comprehensive account of what went wrong, what we tried, and how we fixed it.

What Broke with Tailwind CSS v4?

• Tailwind v4 removed support for older PostCSS plugins and certain configuration patterns (e.g., @theme, legacy safelist, etc.).
• Our custom global styles were not applied.
• Many utility classes silently failed or were purged due to changes in JIT compilation.
• Sourcemaps and HTML build artifacts behaved differently in Turbopack, causing confusion during debugging.
• Turbopack builds were bloated and unpredictable for production.

Attempts to Fix Tailwind v4 Issues

1. Tried the official upgrade path (npx tailwindcss/upgrade)
2. Reinstalled Tailwind v4, PostCSS, Autoprefixer with matching versions
3. Modified the tailwind.config.ts to match the new format
4. Cleaned up custom CSS files and removed deprecated syntax (@theme)
5. Tried configuring Turbopack and fallback to Webpack
6. Inspected build output and DOM to debug purged classes

Despite all efforts, the issues persisted.

The Final Fix: Rolling Back to Tailwind CSS v3.3.5

1. Uninstalled v4 packages

npm uninstall tailwindcss postcss autoprefixer

2. Reinstalled Tailwind v3.3.5 and compatible tools

npm install -D tailwindcss@3.3.5 postcss@8.4.24 autoprefixer@10.4.14

3. Cleaned the project

npm run clean  # Custom script: rm -rf .next node_modules package-lock.json
npm install

4. Fixed global styles (globals.css)

• Removed any use of @theme or @tailwindcss/postcss
• Moved body styling inside @layer base
• Reorganized font and animation definitions
• Removed v4-only utilities and fallbacks

All classes now apply as expected.

5. Updated tailwind.config.ts

• Ensured the content array is compatible with Tailwind v3
• Removed unsupported Turbopack keys
• Validated custom font, color, and spacing definitions

import type { Config } from 'tailwindcss'

const config: Config = {
  content: ['./src/**/*.{js,ts,jsx,tsx,mdx}'],
  safelist: ['text-white', 'bg-kovaad-red', 'font-sans', 'font-helvetica'],
  theme: {
    extend: {
      fontFamily: {
        sans: ['Helvetica', 'sans-serif'],
        twemoji: ['var(--font-twemoji_mozilla)', 'sans-serif'],
      },
      colors: {
        'kovaad-red': '#EF3D3D',
        // other custom colors...
      },
    },
  },
  plugins: [],
}

export default config

Cleaned Up package.json

Removed unnecessary dependency:

"@tailwindcss/postcss": "^4.1.4"

Confirmed working versions:

"tailwindcss": "^3.3.5",
"postcss": "^8.4.24",
"autoprefixer": "^10.4.14"

Takeaways

• Tailwind v4 is still evolving. Unless you're building something from scratch or are fully aligned with its changes, v3 is still the safer bet.
• Custom global CSS, older PostCSS tooling, and frameworks like Next.js (especially with Turbopack) are not always v4-ready.
• If something works in v3 and you don't need v4's bleeding edge features, stick with it.

Next Steps

We'll revisit Tailwind v4 after it matures further and aligns better with our build tooling. Until then, v3.3.5 remains our rock-solid base.

Hope This Helps

If you're stuck trying to tame Tailwind v4, you're not alone. Sometimes, the smartest move is to step back and wait for the dust to settle.

Continue the Discussion

If your frontend stack is in a similar transition and you want help with migration planning, risk control, and release stability, book a CTO consultation.

You can also connect with me on LinkedIn to discuss your current setup.