W

h

a

t

'

s

N

e

w

I

n

T

a

i

l

w

i

n

d

C

S

S

v

4

.

0

A

n

d

H

o

w

T

o

M

i

g

r

a

t

e

T

o

I

t

Tailwind CSS v4.0 is here! and introduces some significant changes that improve performance and refine the developer experience.

There’s a huge amount to cover, but let’s take a look over some of the key changes that will revolutionise the way you write CSS.

The newest version of Tailwind CSS, version 4.0 utilises the Oxide engine which incorporates Lightning CSS. As with most modern tooling, the speed gains of rust are being leveraged to introduce extremely favourable developer experience gains.

Rust allows us to utilise multi-threading and parallelisation to execute computation quickly. Its main goal is to minify a huge amount of CSS and to do so quickly.

	v3.4	v4.0	Improvement
Full build	378ms	100ms	3.78x
Incremental rebuild with new CSS	44ms	5ms	8.8x
Incremental rebuild with no new CSS	35ms	192µs	182x

One of the biggest changes in v4.0 is that Tailwind is now exclusively ESM (ECMAScript Modules). This means Tailwind must be imported using import instead of require.

This aligns with modern JavaScript practices and improves compatibility with newer tooling.

Example of how to import Tailwind in ESM:

If you're still using CommonJS, you’ll need to migrate to ESM. More on that in the migration section below.

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:

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

Then in your HTML

All major browsers today support container queries. Previously, you had to install @tailwindcss/container-queries plugin to get this done.

Now you can do it natively with @container directive.

It has also added support for max-width container queries using the new @max-* variant. This can be used to stack these variants to define container query ranges.

Tailwind CSS v4.0 now requires Node.js 16 or later. If you’re using an older version, you’ll need to upgrade your Node.js environment. You can chek your current version by running:

If you need to update, install the latest version via NVM:

or if you’re using volta:

Tailwind CSS v4.0 automatically removes unused styles by default. This means you no longer need to configure purge or content manually. This results in significantly smaller CSS files, making your apps faster.

Tailwind v3.x

Tailwind v4.0

The content configuration is inferred automatically based on your project's file structure, reducing boilerplate configuration.

Tailwind v4.0 introduces a CSS-first approach, allowing developers to configure design tokens, breakpoints, and more directly in the CSS file instead of the tailwind.config.js. This simplifies the setup and makes the workflow more intuitive.

Tailwind v4.0 introduces design tokens as CSS variables, allowing for greater runtime flexibility. Colors, fonts, and breakpoints can now be defined as CSS variables and dynamically referenced across the project.

Tailwind v4.0 introduces design tokens as CSS variables, allowing for greater runtime flexibility. Colors, fonts, and breakpoints can now be defined as CSS variables and dynamically referenced across the project.

Additionally, native CSS cascade layers are now supported, giving developers greater control over the order of styles and ensuring that higher layers don’t unintentionally override lower ones. This leads to more predictable and organised CSS output

Tailwind v4.0 introduces new defaults for colors, spacing, and shadows, making designs look more modern out of the box.

For example:

If you rely on Tailwind’s default styles heavily, you might notice subtle visual differences when upgrading.

Simplified CSS imports

With the updates to Tailwind v4.0, we only need to import one dependency.

Tailwind v3.x

Tailwind v4.0

If you’re currently using Tailwind v3.x and want to upgrade, follow these steps to ensure a smooth transition.

A Migration Tool to Simplify the Transition

Tailwind CSS offers an upgrade tool that automates most of the required changes. It requires Node.js 20 or later, so ensure your environment is up to date before running it.

This tool will update your dependencies, migrate your configuration files, and adapt your template files.

The Manual Approach

Upgrade Tailwind

Run the following command to update Tailwind to the latest version:

or

Update Your tailwind.config.js

Rename tailwind.config.js to tailwind.config.mjs to support ESM by converting any require() imports to import.

If your tailwind.config.js includes a content property, you can remove it, If you're using standalone mode, remove @tailwind base; from your CSS.

Tailwind v3.x

Tailwind v4.0

To update the css you will need to make the following changes.

Tailwind v3.x

Tailwind v4.0

Test Your Application

Run your dev server and check for any issues:

Tailwind CSS v4.0 brings tonnes of key simplifications and performance improvements, making the framework even more flexible helping you to write code quicker. While some adjustments are required, the migration process is straightforward, especially with the provided tools.

To find out more about all the changes in Tailwind v4.0 head over to the tailwind docs.

Halpy coding,