Next.js and Tailwind Integration Internals

The plain-language idea

Tailwind doesn't generate CSS for every class it could produce — that would be an enormous stylesheet. Instead, at build time it scans the files matched by its content globs as plain text, using a regex-based extractor to pull out anything that looks like a class name, and only generates CSS for the exact strings it finds. It never imports, parses as JavaScript, or executes any of those files — it just greps them.

That's the entire source of the classic bug: className={`text-${color}-500`} never appears anywhere in your source as the literal string text-red-500 or text-blue-500 — it appears as the template string itself. Tailwind's scanner doesn't know color will be "red" at runtime; it can't, because it isn't running your code. It just doesn't see that class as a string that exists, so it never generates CSS for it. No error, no warning — the class is simply absent from the final stylesheet, and the element renders unstyled.

See it in a real thing: a status badge with a dynamic color

This looks completely reasonable and silently fails:

// app/status-badge.tsx
function StatusBadge({ status }: { status: "ok" | "warn" | "error" }) {
  const color = status === "ok" ? "green" : status === "warn" ? "yellow" : "red";
  // Tailwind never sees "text-green-500", "text-yellow-500", or "text-red-500"
  // as literal strings — only this template expression.
  return <span className={`text-${color}-500`}>{status}</span>;
}

The fix is to write every class Tailwind needs to generate as a complete, literal string somewhere in the scanned source — a lookup object works well and doubles as documentation of exactly which variants exist:

// app/status-badge.tsx
const COLOR_BY_STATUS = {
  ok: "text-green-500",
  warn: "text-yellow-500",
  error: "text-red-500",
} as const;

function StatusBadge({ status }: { status: keyof typeof COLOR_BY_STATUS }) {
  return <span className={COLOR_BY_STATUS[status]}>{status}</span>;
}

Now text-green-500, text-yellow-500, and text-red-500 each appear as complete literal strings in a file the App Router build already includes in Tailwind's scan — the scanner finds all three regardless of which one status resolves to at runtime.

What people usually miss

Watch out

• This fails completely silently. There's no build error, no runtime warning, no lint rule catching it by default — the only symptom is an element that looks unstyled, which reads like a CSS specificity bug or a typo, not a missing-class problem.
• Concatenation is just as invisible as interpolation. "text-" + color + "-500" is exactly as unscannable as the template-string version — the scanner is looking for complete literal strings, and neither approach produces one anywhere in the source.
• A conditional between two complete literal strings is fine. className={isActive ? "text-green-500" : "text-gray-400"} works, because both full strings are literally present in the file for the scanner to find — the failure mode is specifically about a class built by assembling pieces at runtime, not about conditional logic itself.

The genealogy: this is a build-time static-analysis problem, not a Next.js one

Nothing about this is App-Router-specific — it's a direct consequence of how Tailwind's own content-scanning step works, which this track's build-system lesson touches on for Next.js's own compiler. The pattern to internalize generalizes past Tailwind: any tool that extracts information from your source by scanning it as text, rather than executing it, can only see what's written as a complete, literal value.