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!
Top comments (12)
Since v4 removed
tailwind.config.js
, setting up UI libraries like shadcn (and others that depend on it) will fail because shadcn requires that file for component installation. If the file isn't present, it throws an error indicating it couldn't find it. I faced these issues, so I downgraded to tailwind@3.4.17. I think if you need to work with ui libraries better not to update right now . Please correct me if I missed something. Thank you.You can use it without that file. Check out this article: luisball.com/blog/shadcn-ui-with-t...
That's not quite correct. You are still able to use the
tailwind.config.js
. You just have to import it into yourglobal.css
or wherever you want to setup Tailwind to. Just check this out: tailwindcss.com/docs/upgrade-guide...That is true! Yesterday, I too (forcibly) downgraded to v3 for shadcn to work
Check this: luisball.com/blog/shadcn-ui-with-t...
How to downgrade?
Is anyone facing issues with Vite? I installed
@tailwindcss/vite
as a dependency following the documentation. Then, invite.config.ts
, I added the import:However, Iβm getting an error saying that the module
@tailwindcss/vite
could not be found. Has anyone encountered this issue before or found a solution?Can you double-check that you really installed it?
Yes it is there and installed properly.

Can you delete your
node_modules
andpackage-lock.json
and reinstall your packages? Also, looking at yourpackage.json
, you should consider moving@types/*
,tailwindcss
, and other dependencies which are only used during development todevDependencies
.Thank you, very helpful
Iβm happy it was helpful.