Use when Tailwind classes work in development but disappear in production builds, or when class names assembled at runtime (template literals like bg-${color}-500, server-injected JSON, CMS-driven attributes, i18n strings, user-configured colours) render in the DOM but produce no visible style. This is the most-reported Tailwind issue (tailwindlabs/tailwindcss issue 18136). Prevents the four most common wrong fixes: turning off purge/JIT entirely (no longer possible in v4 and wastes bundle weight in v3), pasting a massive hand-written safelist that drifts out of sync with the design system, listing every possible class as plain strings somewhere in source then deleting them (the cache survives only one build), and monkey-patching the build to ship the full unminified Tailwind output to production. Covers the four supported fixes ranked by preference: (1) map prop to complete static class string via lookup object, (2) inline style for truly arbitrary user values, (3) v3 safelist array and regex pattern with va
Use when Tailwind classes work in development but disappear in production builds, or when class names assembled at runtime (template literals like bg-${color}-500, server-injected JSON, CMS-driven attributes, i18n strings, user-configured colours) render in the DOM but produce no visible style. This is the most-reported Tailwind issue (tailwindlabs/tailwindcss issue 18136). Prevents the four most common wrong fixes: turning off purge/JIT entirely (no longer possible in v4 and wastes bundle weight in v3), pasting a massive hand-written safelist that drifts out of sync with the design system, listing every possible class as plain strings somewhere in source then deleting them (the cache survives only one build), and monkey-patching the build to ship the full unminified Tailwind output to production. Covers the four supported fixes ranked by preference: (1) map prop to complete static class string via lookup object, (2) inline style for truly arbitrary user values, (3) v3 safelist array and regex pattern with variants, (4) v4 @source inline with brace expansion and range syntax {100..900..100} including hover focus prefixes. Explains why Tailwind scans plain text rather than parsing code, why dev-server HMR re-scanning masks the bug, the full brace-expansion grammar, the canonical issue 18136 walkthrough, and the rule that pattern-based v3 safelisting cannot include variants inside the regex. Keywords: tailwind dynamic class, template literal class, bg-${color}-500, classes work in dev not prod, classes missing production, my tailwind styles disappeared, dynamic className not applying, server-injected class no style, CMS color not working tailwind, tailwind safelist, safelist pattern regex, safelist variants array, @source inline, @source inline brace expansion, {hover:,}bg-{red,blue}-{500,700}, range syntax {100..900..100}, @source not, complete class names rule, Tailwind plain text scanning, why does dev work but prod fail, issue 18136, user-configured colour tailwind, i18n string class tailwind, contentful tailwind class, sanity tailwind class, why are classes not generated, dynamic class names not detected.
license
MIT
compatibility
Designed for Claude Code. Requires Tailwind CSS v3.4 or v4.0+.
metadata
{"author":"OpenAEC-Foundation","version":"1.0"}
Tailwind Dynamic Class Names : The #1 Reported Issue
If a class only exists in source code as a fragment (bg-${color}-500,
text-{{variant}}-600, server JSON, CMS attributes), Tailwind never
generates the CSS rule. The DOM gets the class attribute, the
stylesheet does not get the rule, the element renders unstyled.
Companion skills :
tailwind-impl-config-v4 : @source inline directive in depth
Tailwind treats all source files as plain text and does NOT parse
them as code. A class must exist as a literal complete token in
some scanned file to be generated.
This rule is universal across v3 and v4. Template literals, string
concatenation, runtime composition, server-injected strings, and CMS
data are ALL opaque to the scanner.
<!-- NEVER works (no complete token) --><divclass="text-{{ error ? 'red' : 'green' }}-600"></div><divclass={`bg-${color}-500`}></div><div:class="`p-${size}`"></div><!-- ALWAYS works (complete tokens) --><divclass="{{ error ? 'text-red-600' : 'text-green-600' }}"></div><divclass={isError ? '' ''}>
text-red-600
:
text-green-600
</div>
Why Dev Works But Prod Fails
In development the bundler may include the full unpurged Tailwind
output (HMR re-runs the scanner on every save, picking up classes you
just typed in a test). Production builds run purge once against the
shipped source, and any class that never appeared as a complete token
during that one scan is gone.
Some teams discover the bug after pasting a Storybook story or a
markdown demo into the project ; that file briefly contained
bg-red-500, the dev build cached the rule, then the file moved or
was edited and the rule survived in the dev bundle. The prod build
runs from a clean state and discovers no bg-red-500 token anywhere.
Decision Tree : Which Fix
Is the value bounded to a small known set
(e.g. variant: 'primary' | 'secondary' | 'danger')?
├── YES : Fix 1 (static map)
└── NO : Is the value a numeric range from a CMS / API?
├── YES (e.g. user-picked shade 50-950) :
│ ├── v4 : Fix 4 (@source inline with range)
│ └── v3 : Fix 3 (safelist with regex pattern)
└── NO : truly arbitrary colour / size string :
Fix 2 (inline style)
Fix 1 : Static Map (PREFERRED)
ALWAYS use this when the value is bounded to a known set. It is
zero-runtime, fully type-checkable, and the static analyser sees every
class.
Why it works : every class string ('bg-blue-600 hover:bg-blue-500 text-white') is a complete literal token in the source file. The
Tailwind scanner reads it verbatim.
NEVER write className={`bg-${color}-500`} and expect a fix
later. The static map is the fix.
Fix 2 : Inline Style for Arbitrary Values
When the value is truly arbitrary (a hex code from a user colour
picker, a CSS length from a CMS field), NEVER try to express it as a
Tailwind class. Use the style attribute :
For projects on v3 where the set is too large to inline as a map (a
CMS that emits any shade between 50 and 900 for any of fifteen
colours), use the safelist array in tailwind.config.js.
CRITICAL RULE : patterns can only match BASE utility names. NEVER
include variants inside the regex itself :
// WRONG : variants in regex never match
{ pattern: /hover:bg-(red|green)-500/ }
// RIGHT : variants in the variants array
{
pattern: /bg-(red|green)-500/,
variants: ['hover'],
}
Fix 4 : v4 @source inline (PREFERRED for v4)
v4 replaces the safelist config option with the @source inline
CSS directive. The grammar supports brace expansion AND numeric
ranges, generating the Cartesian product in one line.
The empty alternative in {hover:,focus:,} (note the trailing comma)
includes the bare class WITHOUT a variant. So this generates :
underline, hover:underline, focus:underline.
Truly user-typed CSS (a CMS-managed Tailwind class string entered by
non-developers) cannot be exhaustively safelisted because the input
space is unbounded. Two options :
Restrict the input field to a fixed allowlist of approved utility
classes ; pre-safelist exactly that allowlist via Fix 3 or Fix 4.
Convert the editor's affordance to design tokens (colour picker,
size slider) that emit inline style (Fix 2).
NEVER attempt to safelist "all of Tailwind" by including every utility.
The output CSS bloats to megabytes and the JIT performance benefit
disappears.
