Installing and Configuring Tailwind

This chapter of the Tailwind CSS for Beginners series gets Tailwind running in a real project: which packages to install, the tiny CSS entry file everything starts from, and how Tailwind decides which classes to generate. By the end you will have a watch process that compiles a small, optimised stylesheet straight from your templates.

What you need first

Tailwind v4 is a Node-based build tool, so a couple of things should be in place before you start:

• Node.js 20 or newer — the tooling, including the official upgrade tool, expects a current Node release.
• A project folder — a plain folder of HTML pages works, and so does a Laravel, React, Vue or Astro app.
• Basic CSS knowledge — Tailwind generates CSS, so ideas like the box model and specificity from Introduction to CSS still apply.

Option 1: the Tailwind CLI

The standalone command line tool suits static sites and any framework where you just want a stylesheet at the end of the process. Initialise a project and install both packages — in v4 the CLI lives in its own package instead of the main one:

npm init -y
npm install tailwindcss @tailwindcss/cli
npx @tailwindcss/cli -i ./src/input.css -o ./dist/output.css --watch

Expected output:

done in 41ms
wrote dist/output.css, 8.6 kB
watching for changes…

In v3 the same command was npx tailwindcss -i … -o …, so older tutorials will name a package that no longer contains the CLI. Add --minify when you build for deployment to strip whitespace and comments.

Option 2: the Vite plugin

If your project already uses Vite — including Laravel's default frontend setup — the dedicated plugin is the smoothest route, because it hooks into the dev server and handles hot reloading for you:

npm install tailwindcss @tailwindcss/vite
npm run dev

Then register it in vite.config.js by importing tailwindcss from @tailwindcss/vite and adding tailwindcss() to the plugins array. A third option exists for older setups: the PostCSS plugin, which now ships as @tailwindcss/postcss rather than living inside the tailwindcss package as it did in v3.

The CSS entry file

However you build, Tailwind starts from one stylesheet that you create, and in v4 the whole framework arrives through a single import:

/* src/input.css */
@import "tailwindcss";

/* your own base styles can follow */
body {
  font-family: var(--font-sans);
  color: var(--color-slate-800);
}

That import expands into three parts: the theme layer holding every default token, the base layer holding Preflight (Tailwind's modern reset), and the utilities layer that your class names draw from. In v3 you wrote those as three separate directives — @tailwind base;, @tailwind components; and @tailwind utilities; — and they are gone in v4. Finally, link the file your build writes, never the input file:

<link rel="stylesheet" href="/dist/output.css">

Expected output:

The page gains Tailwind's reset — margins removed, headings
unbolded by default, images set to display block — and every
utility class used in your markup starts working.

How Tailwind finds your classes

Source detection is where beginners get stuck, because a class that is never scanned can never be generated. Tailwind v4 starts from the directory of your CSS file and walks up to the project root, scanning every source file it finds while respecting the folders listed in your .gitignore file, so node_modules and your build output are skipped automatically. You only intervene for special cases:

• Templates living in an unusual place: @source "../admin/**/*.blade.php";
• Class names built at runtime, such as "bg-" + color: declare them with @source inline("bg-red-400 text-center"); so they are always generated.
• Legacy JavaScript configuration: load it explicitly with @config "../../tailwind.config.js";.

v4 configuration compared with v3

Common mistakes

• Forgetting the import — an input file without @import "tailwindcss"; compiles to almost nothing, so every class appears broken.
• Linking the wrong file — the browser must receive output.css; the input file contains directives no browser understands.
• Building class names by concatenation — the scanner reads literal strings, so "text-" + size will not generate text-lg unless you safelist it.
• Expecting v3 behaviour — a tailwind.config.js sitting in the folder is ignored in v4 until you load it with @config.
• Targeting ancient browsers — v4 needs Safari 16.4, Chrome 111 or Firefox 128 or newer; older projects should stay on v3.4.

Practice checklist

1. Create a project folder and run the CLI install commands from this chapter.
2. Write src/input.css containing only @import "tailwindcss";.
3. Build an index.html that uses three utilities and link it to dist/output.css.
4. Run the build with --watch, add a new class in the HTML, and confirm the output file grows.
5. Delete the import line, rebuild, and confirm the CSS shrinks to nothing — then put it back.

With a working build behind you, it is time to think the Tailwind way — The Utility-First Approach.