How to add Tailwind CSS to your HTML project

I wrote this back in 2022. Tailwind has changed a lot since then, so this is the current way to do it.

What makes Tailwind great?

Tailwind makes life so much easier for people struggling with vanilla CSS. It gives you low-level utility classes, so you can build a unique design without ever leaving your HTML file. For more information read the official documentation.

What changed in v4?

Four things from the old guide no longer work:

• tailwind.config.js is gone. You now write your settings in your CSS file instead.
• You no longer list your HTML files. v3 made you write out content: ["./src/**/*.html"] so Tailwind knew where to look. v4 finds them on its own.
• The three @tailwind lines became one. @import "tailwindcss"; replaces all of them.
• The command moved. npx tailwindcss was the build command in v3. In v4 that tool lives in a separate package called @tailwindcss/cli, so you have to install it yourself.

That last one causes the most confusion. You follow an old tutorial, run npx tailwindcss init, and get an error, because there is no config file to create anymore and the command no longer exists.

How to add Tailwind to your project?

1. Install Node and a package manager

Before installing Tailwind, you need Node on your computer.

To check if Node is available, open a terminal and type:

node -v

If Node is missing, go to the official website and download it.

You also need a package manager. Node ships with npm, and there are a few alternatives: pnpm, yarn, and bun. Use whichever you prefer. They all install the same packages from the same registry, so none of them will change how Tailwind behaves.

I use pnpm in this guide, so if you are following along literally, the commands will match. If you prefer something else, here is the translation:

That is the only difference. Everything else in this guide is identical either way.

2. Create a project

To create a project we simply need to create a folder. Open a terminal and type the following commands.

We will be building on the desktop. The cd command is used to move between directories:

cd Desktop

The mkdir command creates a new directory, in this case a folder named tailwindProject:

mkdir tailwindProject

Move into the folder we just created:

cd tailwindProject

And create two folders inside it, one for our HTML and one for our CSS:

mkdir src styles

Then create a package.json, which is the file where your dependencies get recorded:

pnpm init

3. Install Tailwind CSS

In the terminal type this command:

pnpm add tailwindcss @tailwindcss/cli

Two packages, not one. tailwindcss is the engine that turns your classes into CSS, and @tailwindcss/cli is the tool you actually run to build the file. In v3 both came in a single package, which is why an old npx tailwindcss command fails on a fresh v4 install.

And to be clear about the step you might be looking for: there is no pnpm tailwindcss init anymore. Nothing to initialise. Move on to the next step.

Now open the project in your favourite code editor. If you use VS Code you can just type:

code .

4. Add Tailwind to your CSS

Inside the styles folder, create a file named tailwind.css (any name works) and add a single line:

@import "tailwindcss";

That one import replaces the three @tailwind directives from v3. You can also use this file for any custom CSS of your own.

5. Skip the config file

This is the step that used to be step 4. In v3 you had to tell Tailwind where your HTML lived:

// You do not need this anymore
module.exports = {
  content: ["./src/**/*.{html,js}"],
}

In v4 Tailwind scans your project automatically, so a plain HTML project needs no configuration at all. Delete tailwind.config.js if you are carrying one over.

When you do want to customise something (colours, fonts, spacing), you do it in the same CSS file using @theme:

@import "tailwindcss";

@theme {
  --color-brand: #f5a623;
  --font-display: "Inter", sans-serif;
}

Every variable you define here becomes a utility class. --color-brand gives you bg-brand, text-brand, border-brand, and so on, for free.

6. Build your CSS

You are almost done. This step turns the one-line file you just wrote into a real stylesheet.

6.1 Open package.json

And add these two scripts:

"scripts": {
  "watch": "tailwindcss -i ./styles/tailwind.css -o ./styles/output.css --watch",
  "build": "tailwindcss -i ./styles/tailwind.css -o ./styles/output.css --minify"
}

Reading that left to right: -i is the input, the file where you wrote @import "tailwindcss";. -o is the output, the finished stylesheet your HTML will link to. --watch stays running and rebuilds every time you save, and --minify strips the whitespace out for when you put the site online.

You may have seen this script called dev in other tutorials. I have called it watch on purpose, because dev makes it sound like it starts a local server, and it does not. Read on.

6.2 Run it

Inside the terminal, type:

pnpm watch

Leave it running in its own terminal tab while you work. If you close it, your styles stop updating.

This does not start a server. There is no localhost address to open. All the command does is watch your HTML for Tailwind classes and write them into output.css. Opening your page is a separate job, which is the next step.

The output only contains classes you actually used, which is why a Tailwind stylesheet stays small even though the library is huge.

7. Start using Tailwind in your HTML

Create an index.html inside your src folder and start writing. Most importantly, don't forget to link the stylesheet to the output.css file:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <link href="../styles/output.css" rel="stylesheet"/>
    <title>Tailwind Starter</title>
</head>
<body class="bg-gray-800">
    <div class="text-center mt-12">
        <h1 class="text-4xl text-yellow-500 font-bold">Heap Heap Arrayy!</h1>
        <p class="text-xl text-white mt-4">I have created my first HTML project using Tailwind.</p>
    </div>
</body>
</html>

Check that the path in your href actually points at your output.css. This is the single most common reason people end up with an unstyled page.

8. Open it in the browser

Because this is a plain HTML project, there is nothing to start. Just double click index.html and it opens.

If you would rather have the page refresh on save, install the Live Server extension in VS Code, then right click index.html and choose "Open with Live Server". That is what gives you a localhost address, not Tailwind. The two run side by side: pnpm watch rebuilds the CSS, Live Server reloads the page.

If the styles are not showing, it is almost always one of these three:

• The href path to output.css is wrong. Open output.css and confirm it is not empty.
• You are still on v3 syntax somewhere, either the @tailwind directives or a bare tailwindcss command with nothing installed.

Just want to try it quickly?

If you are only playing around and do not want a build step at all, drop this in your <head> and skip everything above:

<script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>

It compiles in the browser, so it is slower and not meant for a real site. But for a quick experiment it saves you five minutes.

Thank you for reading. If you have any questions, feel free to contact me.