Getting started with Tailwind v4

Tailwind v4 is here, and with it come a few fundamental changes. This guide will hopefully demystify installing and using Tailwind v4.

Installing

First off, you need to install Tailwind. How you do that will depend on whether or not you're using a framework, and if so, what framework it is.

Frameworks

If you're using a framework like Next, Nuxt, Sveltekit, Solid, and so on, then the Tailwind docs probably have a dedicated guide for you:

https://tailwindcss.com/docs/installation/framework-guides

If you're using something like React or Vue without a framework (ie Next or Nuxt), then your best approach is to use Vite. First scaffold a new Vite project with your JS framework of choice:

https://vite.dev/guide/#scaffolding-your-first-vite-project

Then follow the Tailwind docs for Vite integration:

https://tailwindcss.com/docs/installation/using-vite

If for some reason you want to use PostCSS, you should use Vite to scaffold your new project, then follow the PostCSS installation docs:

https://tailwindcss.com/docs/installation/using-postcss

No framework, just static HTML

Firstly, if you're developing static HTML websites the old fashioned way, I would highly, highly recommend switching to Astro now and joining us in the 21st Century. It's an excellent framework, produces no JS that you don't add yourself, and also makes using Tailwind properly much more viable.

If you just want to try Tailwind out with static files, then this is how to do it.

1. Make a new folder for your project, eg twtest.
2. In that folder, in a terminal, initiate a new npm project with npm init -y. You can skip this step if you're using pnpm, which you should be.
3. Run npm install tailwindcss @tailwindcss/cli .
4. Create a new index.html and input.css file.
5. In input.css enter @import tailwindcss; and save.

6. In your HTML file, add your HTML boilerplate (! in Vs Code), and then add the link to an output CSS file (which you haven't created, yet): e.g.
   
   html<link href="./output.css" rel="stylesheet">
   

7. In your terminal, run
   
   npx @tailwindcss/cli -i ./input.css -o ./output.css --watch
   

8. Add some test Tailwind to your HTML, e.g.
   
   html<h1 class="text-4xl font-bold text-red-500">Hello World!</h1>
   

Open your HTML file in a browser and you should see a big, red Hello World!

Customising your theme

The major user-facing change in Tailwind v4 is that there is no longer a tailwind.config.js file with which to configure your theme and any other customisations. If you're following a video tutorial somewhere and they go to tailwind.config.js, that tutorial is now out of date.

Instead, all customisation is done in your CSS file (e.g. app.css, input.css, global.css, or whatever CSS file has @import "tailwindcss"; in it. Customisation is done mainly via CSS variables.

For example, to add a new colour, you would do the following:

@import "tailwindcss";

@theme {
  --color-brand: #b4d455;
}

This would make that colour available to any utility that uses colours, ie bg-brand, text-brand, and so on. The Tailwind docs have a complete guide to theme customisation:

https://tailwindcss.com/docs/theme

FAQs

My CSS file has squiggly lines and warnings, why?
This is purely a VS Code issue - it thinks you're using CSS, when in fact you're using special CSS, with custom directives. Install the official Tailwind extension, and then set your file language to TailwindCSS, and the squiggly lines will be banished.

Where's the content array?
V3 used a content array to find the files where Tailwind was being used. V4 has done away with this and now uses several clever methods to find your files automagically. For the most part this works well, however if you need to explicitly point Tailwind to a folder you can do so with the @source directive e.g.:

@source "./src/components/"

Where's the safelist function?
There isn't one, at least not 'built in' as it was in V3. Instead, you can simply add a file (e.g. safelist.txt) and add any classes you want to build in that file. Tailwind's automatic content detection will pick them up.

Where's the blocklist function?
Again, there isn't one. However, Tailwind's content detection makes use of the .gitignore file to help it ignore content, so you can just add your paths to the .gitignore file to prevent them being scanned.

Conclusion

This is a basic guide so I won't go into much further depth. 99% of questions can be answered with a simple search on the Tailwind Docs site at tailwindcss.com. If you can't find the answers there, hop on to the Tailwind Discord and we'll do our best to help.