Introduction

Recently, while building a personal blog started with Tailwind CSS v3.4, I was faced with the need to upgrade to the latest version of the utility-first library. Though this migration guide was helpful, I couldn't find resources to include plugins such as @tailwindcss/typography (needed for the prose-related rules) and @tailwindcss/forms (needed for form elements). Hence this article. It will be a short ride.

Prerequisite

It is assumed you have a basic familiarity with the library. Also, I will be using SvelteKit as a framework of choice here but you just need any project where you need to migrate tailwind CSS from v3 to v4.

Implementation

Step 1: Run the tailwind CSS upgrade tool

To ease developers' stress migrating, the team at Tailwind CSS provided a nifty tool that helps to effortlessly migrate between the versions. In your project's root, just run:

$ npx @tailwindcss/upgrade@next

You should accept the installation prompt and watch it do its magic! It will help correct some breaking changes in your code, fix postcss configuration (if you use it), correct the import statements in your main CSS file where tailwind was used, upgrade its version in package.json, etc. In case it can't migrate some stuff, you will be informed.

Step 2: Using plugins

The step above was pretty easy and basic. As I mentioned, the migration guide included that. However, most projects use more than just the basic tailwind setup. For example, you need @tailwindcss/typography for this rule to work:

.content {
  @apply dark:prose-invert prose-headings:font-bold prose-a:no-underline hover:prose-a:underline prose-pre:rounded-lg prose-pre:p-4;
}

without it, you will be greeted with something like:

Cannot apply unknown utility class: dark:prose-invert

In the same vein, without @tailwindcss/forms, you would find it hard to easily work with form elements, especially checkboxes.

In version 3, adding plugins such as the above would be done in tailwind.config.ts:

...
import forms from '@tailwindcss/forms';
import typography from '@tailwindcss/typography';
import type { Config } from 'tailwindcss';

export default {
    ...
    theme: {
        ...
    },
    plugins: [typography, forms,...]
} satisfies Config;

However, with v4, you can ditch that file entirely. Instead, use your main entry CSS file (where you import tailwindcss):

@import "tailwindcss";
@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/forms";
@plugin ...;

with that, tailwindcss will compile easily.

Step 3: Enabling dark mode

By default, v4 uses the awesome prefers-color-scheme media feature to intrinsically support dark mode. However, most of us are used to toggling light/dark themes based on classes. Hence, in v3, we achieved this using tailwind.config.ts:

...
export default {
    ...
    darkMode: 'class',
    theme: {
        ...
    },
    plugins: [...]
} satisfies Config;

In v4, the file will also be ditched. The main entry CSS file comes to the rescue:

@import "tailwindcss";
...

@custom-variant dark (&:where(.dark, .dark *));;

with that, your previous toggling feature comes back to life!

That's it! If you have other tips, don't hesitate to share them.

Outro

Enjoyed this article? I'm a Software Engineer and Technical Writer actively seeking new opportunities, particularly in areas related to web security, finance, healthcare, and education. If you think my expertise aligns with your team's needs, let's chat! You can find me on LinkedIn and X. I am also an email away.

If you found this article valuable, consider sharing it with your network to help spread the knowledge!