What's New and Migration Guide: Tailwind CSS v4.0

Tailwind CSS has just released version 4.0, marking a significant milestone in the evolution of this powerful framework. While this update introduces many improvements and simplifications, it also includes changes that might affect your existing projects. This article provides a step-by-step guide to ensure a smooth migration while exploring the key highlights of this version.

---

1. A Migration Tool to Simplify the Transition

To make migration easier, Tailwind CSS offers an upgrade tool that automates most of the required changes. Here's how to use it:

$ npx @tailwindcss/upgrade@next

This tool will update your dependencies, migrate your configuration files, and adapt your template files. It requires Node.js 20 or later, so ensure your environment is up to date before running it.

Tips:

• Run this tool in a new Git branch to easily compare changes.

• Rigorously test your project in a browser to ensure everything works as expected.

---

2. Major Updates and Changes

Here's an overview of the key changes introduced in Tailwind CSS v4:

a) Removal of @tailwind Directives in CSS

The old directives like @tailwind base; are replaced with a simple import statement:

@import "tailwindcss";

b) Deprecated Utility Changes

Some utility classes have been removed or renamed for better consistency. Here are a few examples:

c) Class Renaming for Sizes

To improve clarity, size classes like shadow-sm are now shadow-xs:

<input class="shadow-xs" />

d) Updates to Ring, Shadow, and Blur Scales

The default ring class now changes from 3px to 1px, aligning with borders and outlines.

<input class="ring-3 ring-blue-500" />

e) New API for Custom Utilities

The @utility API replaces the older @layer utilities, providing a clearer and more structured way to define custom utilities. Here are additional examples illustrating this transition:

@utility margin-auto {
  margin: auto;
}

@utility flex-center {
  display: flex;
  justify-content: center;
  align-items: center;
}

These new declarations enable more explicit management of utility classes in your projects.

@utility tab-4 {
  tab-size: 4;
}

---

3. Improvements for Build Tools

a) Vite

A dedicated plugin for Vite is now available for an enhanced developer experience:

import { defineConfig } from "vite";
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
  plugins: [
    tailwindcss(),
  ],
});

b) Standalone CLI

The Tailwind CLI has been moved to a dedicated package:

npx @tailwindcss/cli -i input.css -o output.css

---

4. Minor Changes in Base Styles

• Default Border Color: Now aligned to currentColor.

• Placeholder Color: Now at 50% opacity of the current text.

To retain v3 behavior:

@layer base {
  input::placeholder {
    color: theme(--color-gray-400);
  }
}

---

5. Recommendations for a Successful Migration

1. Use the migration tool: Most projects can be migrated automatically.

2. Test your project: Adopt an iterative approach to detect potential issues.

3. Consult the documentation: Check for details on changes not handled by the tool.

---

Conclusion

Tailwind CSS v4.0 brings simplifications and improvements that further enhance the framework's efficiency and flexibility. While some adjustments are necessary, the migration tool saves valuable time.

I'm glad you found the article helpful! If you have any questions about migrating to Tailwind CSS v4 or need further assistance, feel free to ask. Your feedback and experiences are valuable, so don't hesitate to share them. And if you enjoyed the article, sharing it with your network would be greatly appreciated!

---