Diagnosing Missing Tailwind Utilities When Classes Are Built Dynamically

The Problem: Classes Work in Dev, Vanish in Production

You run npm run dev and the UI looks correct. After npm run build the same component renders without the expected background, text color, or spacing. Inspecting the production CSS shows the utility class—say bg-red-500—is simply not there. The class string exists in your source, but Tailwind’s JIT scanner never saw it as a complete token.

Takeaway: Tailwind’s content scanner is regex‑based and only detects class names that appear as literal, complete strings in the files it scans. Any runtime construction—template literals, concatenation, array joins—breaks detection.

Root‑Cause Patterns

Pattern	Detected by JIT?	Why It Fails
text-red-500 (static string)	Yes	Full token present in source
text-${color}-500 (template literal)	No	Variable value unknown at scan time
["text-red-500","bg-blue-500"].join(" ")	No	Dynamic expression, no literal tokens
cond ? "text-red-500" : "text-blue-500"	Yes	Both complete classes appear in source
"text-" + color + "-500"	No	Concatenation yields no complete token

Ordered Diagnostic Checks

1. Search for dynamic construction. Run a repo‑wide grep for the patterns that evade the scanner:

   grep -R -E '\$\{|\+.*-|join\(|\?.*:.*-' --include="*.js" --include="*.tsx" --include="*.vue" .

   Run this from the project root. It requires read access to source files. Matches indicate where you must rewrite or safelist.
2. Verify content globs. Open tailwind.config.js and confirm every template, component, and page file is covered. Add a temporary log to see resolved paths:

   // tailwind.config.js
   console.log(JSON.stringify(config.content, null, 2));

   Run npx tailwindcss --help (any command) to print the array. Missing directories are a common cause.
3. Produce a minified build and grep for the missing class.

   NODE_ENV=production npx tailwindcss -i ./src/input.css -o ./dist/output.css --minify
   grep -n "bg-red-500" ./dist/output.css

   Run in the project root with Node ≥ 18. If the class is absent, the scanner missed it.
4. Check for @source inline directives or safelist usage. Look for @source "../components/**" in CSS files or a safelist array in the config. These are intentional overrides; if they’re missing the class, the issue is detection, not purge.

Fixes Mapped to Findings

Template Literals → Enum Mapping

Replace text-${color}-500 with a lookup object that contains full class names:

const colorMap = {
  primary: "text-blue-500",
  danger: "text-red-500",
  warning: "text-yellow-500"
};
// usage
colorMap[theme] // returns a complete token the scanner sees

This keeps the dynamic choice while giving the scanner literal strings.

Array Joins → Inline or Safelist

If you build class lists via join, either write the classes inline where possible or add the finite set to safelist in tailwind.config.js:

safelist: [
  "text-red-500",
  "bg-blue-500",
  "p-4",
  "rounded-lg"
]

Avoid broad regex safelists like { pattern: /bg-.*/ }—they bloat the output CSS with every matching utility.

String Concatenation → Complete Tokens

Rewrite "text-" + color + "-500" using the same enum approach or a helper that returns full class names. If the value truly comes from an external source (CMS, user input), safelist the known possibilities.

Missed Files → Expand content Globs

Add the missing directories to content. For monorepos, use absolute paths or workspace‑relative globs:

content: [
  "./src/**/*.{js,ts,jsx,tsx}",
  "../packages/ui/**/*.{js,ts,jsx,tsx}"
]

Escalation Criteria

If the class still disappears after rewriting dynamic patterns and confirming content coverage, proceed through these steps:

1. Confirm Tailwind version ≥ 3.3. Run npx tailwindcss --version. Older JIT implementations had different scanning quirks.
2. Inspect PostCSS pipeline. Custom plugins (e.g., postcss-purgecss, cssnano with aggressive rules) can strip utilities after Tailwind generates them. Temporarily disable non‑Tailwind plugins and rebuild.
3. Verify @tailwind utilities presence. Open the generated CSS and ensure the directive block exists. If the framework’s integration (Next.js, Vite, Remix) transforms source before Tailwind scans, the scanner may see transpiled output instead of your original templates. Use the framework‑specific Tailwind plugin (e.g., @tailwindcss/postcss for Vite, next-plugin-tailwindcss for Next.js) and point content to pre‑transformed files.
4. Create a minimal reproduction. A single HTML file with a script tag that constructs the class dynamically, then run the Tailwind CLI directly. If the bug persists, file an issue with that repo.

Verification Checklist

• Production build (NODE_ENV=production npx tailwindcss -i input.css -o output.css --minify) includes the previously missing class.
• Grep for dynamic patterns returns zero matches after rewrites.
• console.log of resolved content globs shows every entry point.
• Temporary safelist addition makes the class appear—confirming detection, not purge, was the issue.
• Minimal reproduction with Tailwind CLI alone works, isolating framework integration problems.

Limitations & Practical Notes

• JIT scanning is regex‑based, not AST‑aware. It cannot evaluate imports, runtime variables, or complex expressions.
• Inline @source directives (v3.4+) only work in files Tailwind already processes; they cannot pull in external dynamic strings.
• Framework file transformations (Next.js SWC, Vite Vue SFC) may alter source before Tailwind scans. Ensure content points to pre‑transformed files or use the official framework plugin.
• Safelist bloats output CSS; prefer static enumeration over broad patterns.