DEV Community

hanui-io
hanui-io

Posted on

Tailwind CSS v4 Migration Guide

#tailwindcss #css #frontend #webdev

Tailwind v4 is out. Have you migrated yet?

A lot has changed from v3 to v4. Config files, syntax, and the build system.

What Changed

1. CSS-first Configuration

The biggest change. No more tailwind.config.js required.

// v3: tailwind.config.js required
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: '#3b82f6',
      },
    },
  },
};
Enter fullscreen mode Exit fullscreen mode 
/* v4: configure directly in CSS */
@import "tailwindcss";

@theme {
  --color-brand: #3b82f6;
}
Enter fullscreen mode Exit fullscreen mode

One CSS file does it all.

2. @tailwind → @import 

/* v3 */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* v4 */
@import "tailwindcss";
Enter fullscreen mode Exit fullscreen mode

Down to a single line.

3. Native CSS Variables

v4 generates all values as CSS variables:

/* Variables auto-generated by v4 */
:root {
  --color-blue-500: #3b82f6;
  --spacing-4: 1rem;
  --font-size-lg: 1.125rem;
}
Enter fullscreen mode Exit fullscreen mode 
/* Use directly in your CSS */
.custom-box {
  background: var(--color-blue-500);
  padding: var(--spacing-4);
}
Enter fullscreen mode Exit fullscreen mode

Use variables directly without Tailwind classes.

Migration Steps

Step 1: Upgrade Package 

npm install tailwindcss@latest
Enter fullscreen mode Exit fullscreen mode

Step 2: Update CSS File 

/* old globals.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* ↓ change to */
@import "tailwindcss";
Enter fullscreen mode Exit fullscreen mode

Step 3: Migrate Config (Optional)

Move existing config to CSS or keep as is:

/* Moving to CSS */
@import "tailwindcss";

@theme {
  /* Custom colors */
  --color-brand: #3b82f6;
  --color-brand-dark: #2563eb;

  /* Custom fonts */
  --font-family-sans: 'Inter', sans-serif;

  /* Custom spacing */
  --spacing-18: 4.5rem;
}
Enter fullscreen mode Exit fullscreen mode 
// Keeping JS config (v4 supports this too)
// tailwind.config.js
export default {
  theme: {
    extend: {
      colors: {
        brand: '#3b82f6',
      },
    },
  },
};
Enter fullscreen mode Exit fullscreen mode

Both work. Migrate gradually to CSS if you prefer.

Syntax Changes

1. Opacity Syntax 

<!-- v3 -->
<div class="bg-blue-500/50">

<!-- v4 (same) -->
<div class="bg-blue-500/50">
Enter fullscreen mode Exit fullscreen mode

No change here.

2. Arbitrary Values 

<!-- v3 -->
<div class="w-[200px] bg-[#ff0000]">

<!-- v4 (same) -->
<div class="w-[200px] bg-[#ff0000]">
Enter fullscreen mode Exit fullscreen mode

Same as before.

3. Container Queries

Built-in support in v4:

<!-- v3: needed @tailwindcss/container-queries plugin -->
<!-- v4: works out of the box -->
<div class="@container">
  <div class="@lg:grid-cols-2">
    Changes based on container size
  </div>
</div>
Enter fullscreen mode Exit fullscreen mode

4. 3D Transforms 

<!-- New in v4 -->
<div class="rotate-x-45 rotate-y-30 perspective-500">
  3D transforms
</div>
Enter fullscreen mode Exit fullscreen mode

Common Errors

1. PostCSS Config 

// postcss.config.js - for v4
export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};
Enter fullscreen mode Exit fullscreen mode

Use @tailwindcss/postcss instead of tailwindcss.

2. @apply Warnings 

/* v4 may warn about @apply */
.btn {
  @apply px-4 py-2 bg-blue-500;
}
Enter fullscreen mode Exit fullscreen mode

v4 discourages @apply. CSS variables are preferred:

/* Recommended approach */
.btn {
  padding: var(--spacing-2) var(--spacing-4);
  background: var(--color-blue-500);
}
Enter fullscreen mode Exit fullscreen mode

3. Plugin Compatibility

Some v3 plugins may not work with v4. Check compatibility:

# Official plugins mostly supported
npm install @tailwindcss/forms@latest
npm install @tailwindcss/typography@latest
Enter fullscreen mode Exit fullscreen mode

When to Migrate

Good to Go Now

  • New projects
  • Projects with minimal custom config
  • Want to leverage CSS variables

Wait a Bit

  • Heavy legacy plugin usage
  • Extensive @apply usage
  • Production stability is priority

v4 Benefits

  1. Build Speed: Oxide engine is much faster
  2. Simpler Config: CSS-first reduces config files
  3. Native CSS Variables: Easier design token usage
  4. Bundle Size: More optimized output

Summary

v4 Migration Checklist:

  • [ ] Install tailwindcss@latest
  • [ ] Change @tailwind → @import "tailwindcss"
  • [ ] Update postcss.config.js
  • [ ] Move custom config to @theme (optional)
  • [ ] Check plugin compatibility
  • [ ] Review @apply warnings

No rush. v3 will be maintained for a while. Use v4 for new projects, migrate existing ones gradually.

Top comments (0)