Next.js 16 + Tailwind CSS v4 Migration Guide: What Actually Broke

Get the AI Readiness Audit Enterprise IBM Stack

I migrated this site — [tostupidtooquit.com](https://tostupidtooquit.com) — from Next.js 15.1 with Tailwind CSS v3.4 to Next.js 16 with Tailwind CSS v4 in February 2026. The Next.js 16 + Tailwind CSS v4 migration guide you'll find in the official docs covers the happy path. This post covers everything else: the runtime behavior changes that broke production, the config restructuring that invalidated half my muscle memory, and the Turbopack-only gotchas that don't show up until you deploy.

I'm writing this because every "migration guide" I found was either a changelog summary or a tutorial written by someone who hadn't actually shipped the migration. This is what happened when I ran the upgrade on a real production site with middleware, dynamic imports, server components, and a CSP policy.

What Changed: The Executive Diff

Before I get into specifics, here's the high-level scope of what moved:

|------|--------------------------|--------------------------|-----------|

| Content scanning | content: ["./src//*.tsx"] | Automatic source detection | Config removal |

Next.js 16 + Tailwind CSS v4 Migration: Step-by-Step

Step 1: Upgrade Dependencies

pnpm add next@16 react@19 react-dom@19
pnpm add -D tailwindcss@4 @tailwindcss/postcss
pnpm remove autoprefixer

Tailwind v4 handles vendor prefixing internally. Autoprefixer is dead weight now.

If you're using @tailwindcss/typography or @tailwindcss/forms, check compatibility. Typography was folded into core in v4.1. Forms still exists as a separate package but the API changed.

Step 2: Delete tailwind.config.ts

This is the biggest mental shift. Tailwind v4 is [CSS-first configuration](https://tailwindcss.com/docs/v4-beta). Your tailwind.config.ts is replaced by directives in your CSS file. Before — tailwind.config.ts:

import type { Config } from "tailwindcss";
const config: Config = {
  content: [
    "./app//*.{ts,tsx}",
    "./components//*.{ts,tsx}",
  ],
  theme: {
    extend: {
      colors: {
        primary: "#0f62fe",
        accent: "#6929c4",
        background: "#060810",
        foreground: "#e5e5e5",
      },
      fontFamily: {
        sans: ["var(--font-space-grotesk)", "system-ui", "sans-serif"],
        mono: ["var(--font-jetbrains-mono)", "monospace"],
      },
    },
  },
  plugins: [],
};
export default config;

After — app/globals.css:

@import "tailwindcss";
@theme inline {
  --color-primary: oklch(0.55 0.24 264);
  --color-accent: oklch(0.42 0.19 293);
  --color-background: oklch(0.12 0.02 264);
  --color-foreground: oklch(0.91 0 0);
  --font-sans: var(--font-space-grotesk), system-ui, sans-serif;
  --font-mono: var(--font-jetbrains-mono), monospace;
  --animate-fade-in-up: fade-in-up 0.6s ease-out both;
}
@keyframes fade-in-up {
  from {
    opacity: 0;
    transform: translateY(12px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

A few things that caught me:

@theme inline means the generated CSS variables are inlined directly, not wrapped in a :root selector. If you omit inline, Tailwind generates a @layer theme { :root { ... } } block, which changes cascade order.

OKLCH colors are not optional in v4's default palette. The built-in colors (blue-500, gray-200, etc.) are all OKLCH now. If you're defining custom colors, you can use hex, rgb, or oklch — but mixing hex custom colors with the OKLCH default palette produces visible contrast inconsistencies in dark themes. I converted everything to OKLCH to stay consistent.

No content array. Tailwind v4 scans your source files automatically. It finds .tsx, .ts, .jsx, .js, .html, .vue, and .svelte files in your project. If you need to include non-standard paths (like a component library in node_modules), use @source:

@source "../node_modules/@my-design-system/components";

The extend concept is gone. In v3, theme.extend.colors.primary added to the defaults. In v4, defining --color-primary in @theme just... sets it. There's no distinction between extending and overriding.

Step 3: Update postcss.config

Before:

module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};

After — postcss.config.mjs:

export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

That's it. One plugin. Autoprefixer is bundled.

Step 4: Fix Class Name Changes

Tailwind v4 renamed or restructured several utilities. This table covers the ones that actually hit me:

| v3 Class | v4 Class | Notes |

|----------|----------|-------|

| bg-opacity-50 | bg-black/50 | Opacity modifiers are now the only way |

| text-opacity-75 | text-white/75 | Same — slash syntax replaces -opacity- |

| decoration-2 | decoration-2 | Unchanged, but decoration-solid is now decoration-line-solid |

| ring-offset-2 | ring-offset-2 | Unchanged |

| blur-sm | blur-xs / blur-sm | blur-sm radius decreased; old blur-sm ≈ new blur-md |

| shadow-sm | shadow-xs / shadow-sm | Same shift — sizes shifted down |

| rounded-sm | rounded-xs / rounded-sm | Border radius scale shifted |

| p-[10px] | p-[10px] | Arbitrary values unchanged |

| space-x-4 | gap-x-4 with flex | space- still works but gap- is preferred |

The blur-sm → blur-xs rename caused the most visual regressions for me. I had subtle glass effects throughout the site using blur-sm and blur-3xl. The blur radii all shifted, so what was a gentle frosted glass became either too sharp or too diffuse. I had to visually audit every blur usage.

Step 5: Migrate Custom Animations

In v3, custom animations lived in tailwind.config.ts:

theme: {
  extend: {
    animation: {
      "fade-in-up": "fade-in-up 0.6s ease-out both",
    },
    keyframes: {
      "fade-in-up": {
        from: { opacity: "0", transform: "translateY(12px)" },
        to: { opacity: "1", transform: "translateY(0)" },
      },
    },
  },
},

In v4, they go in CSS:

@theme inline {
  --animate-fade-in-up: fade-in-up 0.6s ease-out both;
}
@keyframes fade-in-up {
  from {
    opacity: 0;
    transform: translateY(12px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

Then className="animate-fade-in-up" works as before. The convention is --animate-{name} in @theme.

The Next.js 16 Turbopack Migration Landmines

This is where the Next.js 16 + Tailwind CSS v4 migration gets interesting. Tailwind v4 was straightforward — tedious but predictable. The Next.js 16 changes were behavioral and often didn't surface until build time or production.

`next/dynamic` with `ssr: false` in Server Components

This one killed my deploy pipeline for two hours. In Next.js 15, this was fine in a Server Component:

// app/page.tsx — Server Component
import dynamic from "next/dynamic";
const P5Background = dynamic(
  () => import("@/components/p5-background"),
  { ssr: false }
);

In Next.js 16 with Turbopack, this throws a build error:

Error: ssr: false is not allowed with next/dynamic in Server Components.
Move it to a Client Component.

The fix: create a client wrapper component.

// components/p5-background-lazy.tsx
"use client";
import dynamic from "next/dynamic";
export const P5BackgroundLazy = dynamic(
  () => import("@/components/p5-background"),
  { ssr: false }
);

// app/page.tsx — Server Component
import { P5BackgroundLazy } from "@/components/p5-background-lazy";
export default function Home() {
  return (
    <>
      <P5BackgroundLazy />
      {/ rest of page /}
    </>
  );
}

This is documented in the [Next.js 16 upgrade guide](https://nextjs.org/docs/app/building-your-application/upgrading), but it's buried under "Breaking Changes" in paragraph form. If you have next/dynamic with ssr: false anywhere in a Server Component, it will break. grep -r "ssr: false" app/ before you deploy.

Middleware Naming Deprecation

Next.js 16 started a rename from middleware.ts to proxy.ts. As of 16.2, both work, but you'll see a console deprecation warning on every request:

⚠ middleware.ts is deprecated. Rename to proxy.ts.

It's cosmetic. I haven't renamed mine because some deployment platforms and CDN configs reference middleware explicitly, and I don't want to chase edge cases on a cosmetic change. The function signature and behavior are identical.

TypeScript in next.config

Next.js 16 supports next.config.ts natively — no more .mjs with @ts-check hacks. The migration: Before — next.config.mjs:

/ @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    turbo: {},
  },
};
export default nextConfig;

After — next.config.ts:

import type { NextConfig } from "next";
const nextConfig: NextConfig = {
  // Turbopack is now default — no experimental flag needed
};
export default nextConfig;

Image `sizes` Attribute Behavioral Change

Turbopack's image optimization pipeline handles next/image sizes differently than Webpack did. In Next.js 15, omitting sizes on a responsive image generated a reasonable default srcset. In Next.js 16, omitting sizes generates a full-width srcset that ignores your layout constraints. Always specify sizes explicitly now:

<Image
  src="/og-image.png"
  alt="Open Graph preview"
  width={1200}
  height={630}
  sizes="(max-width: 768px) 100vw, 50vw"
/>

The CSS Cascade Subtle Break

This one doesn't show up in any migration guide I've found, and it cost me three hours of debugging.

Tailwind v3 injected utilities at the end of the stylesheet, giving them high specificity by default. Tailwind v4 uses [CSS Cascade Layers](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Cascade_layers):

@layer theme, base, components, utilities;

This means any unlayered CSS you have automatically wins over Tailwind utilities, because unlayered styles beat layered styles in cascade order. If you have a global stylesheet with:

.hero-title {
  color: white;
}

This will override text-primary in v4, where it wouldn't have in v3. The fix: put your custom CSS in a layer:

@layer components {
  .hero-title {
    color: white;
  }
}

Or better, convert it to Tailwind utilities and delete the custom CSS entirely. I chose the latter for everything except third-party embed styles (Calendly) that I couldn't control.

The Production CSP Policy Problem

If you're running a Content Security Policy (I am — strict-dynamic with nonces), Tailwind v4's build output changed in a way that affects CSP. In v3, Tailwind generated a single CSS file with all utilities. In v4 with Turbopack, CSS is code-split per route, and the CSS module loading uses inline