Inside the Engine

Tailwind CSS Fundamentals taught you to write the classes. This course is about running Tailwind in real projects, and almost every real-project problem (a class that does nothing, a stylesheet that is bigger than expected, old CSS that refuses to be overridden) comes down to the same question: what does Tailwind actually do between your markup and the CSS file? This chapter opens the box. You will see what the scanner reads and what it skips, how to point it at the files it misses, why class names built in code vanish, what the generated file is made of, why a single unlayered rule beats every utility, and what the final optimisation step changes.

The Pipeline in One Picture

Tailwind v4 does four jobs, in order. Knowing which one is misbehaving is most of the skill of debugging it:

The most important consequence is in step 1. The scanner does not parse JavaScript, HTML or Markdown; it only looks for words. It cannot tell a class attribute from a sentence. I proved that with a Markdown file that contains no markup at all:

Five utilities were generated from a sentence. That is harmless, apart from a few extra bytes, but it explains two things you will see later: classes in comments and strings count, and a class name assembled from parts is invisible, because the finished word never appears in any file.

What the Scanner Reads, and What It Skips

By default v4 needs no content list. It scans the project from the current directory and skips what is clearly not source. To see exactly where the line falls, I put one distinct colour class in each kind of file, built, and checked which colours came out:

One detail surprised me, so I tested it twice: the .gitignore is honoured even when the folder is not a git repository. I ran the build before and after git init and the answer was identical (red, orange and teal only). The consequence is practical: a class that lives only in a generated or ignored folder will quietly not exist.

Telling the Scanner Where to Look

Three tools in your CSS file change what is scanned. All of them were run against the same nine files above, and the colours that appeared are in the last column.

Two more rules from my runs. First, paths in @source are relative to the CSS file that contains them: with the CSS file in css/, I needed @source "../src" and it found red and orange. Second, naming a folder does not make Tailwind read file types it never reads: even with @source "./src", the class in src/styles.css never appeared.

Classes the Scanner Cannot See

This is the failure that costs the most time. Here is a badge function that builds its colour from an argument, and the check I ran on the output:

The browser receives bg-red-600, but the scanner only ever sees the file, where the text is bg-${color}-600, and that is not a class. The same goes for "text-" + "red-600". Nothing warns you. There are three fixes, in order of preference:

@source inline() is the v4 replacement for the old safelist option, and it understands brace expansion, number ranges and variants. This single line, built and listed, produced all of the classes below:

Look at the last line of the input. @source not inline("bg-red-{100,200}") removed exactly the two plain classes it named, and the hover: and focus: versions of the same colours stayed. It matches whole class names, so to remove the variants you must list them as well. The braces generate every combination, so keep the sets small: @source inline("{hover:,focus:,}bg-red-{50,{100..900..100},950}") is 33 classes from one line, and a careless range can add thousands.

Reading the Output

A small page (one button with six classes) builds to 188 lines and 5,191 bytes. Almost all of that is the same every time. The structure is what to read:

Theme variables are written only when something uses them. I defined three tokens and used one:

Plain @theme keeps your file small; @theme static (or the static option) forces a variable out even when nothing uses it, which you need when other CSS or JavaScript reads it with var(--color-always) or getComputedStyle. Chapter 2 (Tailwind CSS Intermediate/Advanced 2) builds a whole token system on this.

Layers and the Cascade: Why Plain CSS Beats Utilities

Cascade layers change the order in which rules compete. The relevant fact, which is easy to miss because layers are new to many developers: CSS that is not inside any layer beats CSS that is inside a layer, whatever the specificity. Tailwind puts every utility inside @layer utilities, so any ordinary rule you write at the top level of a stylesheet outranks them. I tested four placements of an identical font-size: 10px rule against text-xl (20px) on the same elements, and read the result from Chrome:

That gives the working rules for any stylesheet in a Tailwind project:

• A rule in @layer components can be overridden by a utility on the element, which is the behaviour you want from a component class. It is why Tailwind provides that layer.
• An unlayered rule beats a utility. This is the usual explanation when "my p-8 does nothing" on an element that an older stylesheet also styles.
• Inside one layer, the normal rules apply: higher specificity wins, then the later rule.

The clean fix for old CSS is not to raise specificity or add !important, but to put the old stylesheet into a layer. A legacy rule .btn { padding: 4px; background-color: gray; } used on class="btn p-8 bg-blue-600":

What Lightning CSS Does

The last step runs your CSS through Lightning CSS. The default build leaves most of your own CSS alone; --optimize and --minify rewrite it. I gave the CLI a rule that uses nesting, a prefixed property and color-mix(), and built it three ways:

Three observations from that run, each worth knowing before you debug a production-only difference:

• The nesting was flattened (to .card:hover and .card .title), the vendor prefix was added (-webkit-user-select), and color-mix() with two fixed colours was computed (#609). The tool lowers your CSS for the browsers it targets.
• --optimize was bigger than the default build, not smaller. I expected the opposite. Flattening and splitting grouped selectors into separate rules adds text; only --minify shrinks the file, and it also does the optimising.
• The layer-order line disappears in optimised output (@layer theme, base, components, utilities; is gone), but the order is kept: the layers still appear in sequence, with an empty @layer components; placeholder holding the third position.

So the rule is: compare like with like. If a bug shows only in production, build the development CSS with --minify locally and test that.

Watch Mode

--watch keeps the compiler running and rebuilds when a scanned file changes. I started it on a project with one file, then edited a class, then added a new file. The file lists after each step:

New files are picked up without restarting. Plain --watch stops when standard input closes (which happens under some task runners and CI jobs); --watch=always keeps going. The option list also has --poll for file systems that do not report changes. I did not test polling.

Hands-On Exercises