Migrating to Tailwind CSS v4: What You Need to Know

The Big Shift: CSS-First

Tailwind CSS v4 is the biggest update since Tailwind first launched. The headline change: your configuration moves from JavaScript to CSS.

Gone is tailwind.config.ts. In its place, you use @theme blocks directly in your CSS.

Before and After

Tailwind v3 (JavaScript config):

// tailwind.config.ts
export default {
  theme: {
    extend: {
      colors: {
        primary: "#6366f1",
      },
    },
  },
};

Tailwind v4 (CSS-first):

@theme inline {
  --color-primary: #6366f1;
}

The CSS approach is simpler, faster, and keeps your design tokens where they belong.

Key Changes

1. No More Config File

Delete your tailwind.config.ts. All customization happens in CSS via @theme.

2. New Engine (Oxide)

v4 uses a completely rewritten engine called Oxide. Build times are significantly faster — especially noticeable on large projects.

3. CSS Variables by Default

All theme values are available as CSS variables automatically. This makes dark mode, animations, and dynamic theming much easier.

4. PostCSS Plugin Change

The PostCSS plugin name changed:

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

Migration Steps

1. Update your dependencies: tailwindcss@4, @tailwindcss/postcss@4
2. Delete tailwind.config.ts
3. Move your theme customizations to @theme blocks in CSS
4. Update your PostCSS config to use @tailwindcss/postcss
5. Replace @tailwind base/components/utilities with @import "tailwindcss"
6. Test everything — most utility classes are unchanged

Is It Worth It?

Yes. The build performance improvements alone are worth the migration. Add in the cleaner configuration approach and better CSS variable support, and v4 is a clear upgrade.

The migration is straightforward for most projects. Set aside an afternoon and you'll be done.