Tailwind CSS utility generation vs runtime‑composed class names: safelist or source refactor

Answer

When you control the source of the class string, refactor to literal names. Keep the safelist minimal for truly external markup (CMS, third‑party HTML). This split keeps the build lean, preserves linting, and makes intent visible.

Maintainability & Readability

Literal class names stay in the template, so the visual intent is immediately obvious. A small refactor – for example, a variant map – can replace concatenation without changing the UI:

const variantClasses = {
  danger: 'bg-red-500 text-white',
  success: 'bg-green-500 text-white',
};
<div className={variantClasses[tone]}>…</div>

In contrast, a safelist decouples usage from generation. Removing the last consumer of a safelisted class leaves the utility in the CSS forever unless the config is updated, which can lead to bloated stylesheets.

Build Reproducibility & Cache Invalidation

• Safelist edit – changes the tailwind.config.js file, a direct input to the compiler. Any edit forces a full CSS rebuild and invalidates the cache, even if no template changed.
• Literal refactor – only the files that actually change are re‑scanned. Incremental builds hit the cache more often, keeping build times short.

Both produce the same final CSS for the same inputs, but the refactor path yields finer‑grained cache hits and smaller bundles.

Linting & Team Conventions

ESLint plugins, Stylelint, and Tailwind CSS IntelliSense only understand literal strings. Safelisted patterns are invisible to these tools, so autocomplete and typo detection are lost. If your team already enforces utility‑class rules, literal names stay in sync with the linting configuration.

Concrete Steps

1. Audit dynamic classes – list all runtime‑generated strings.
2. If source‑controlled – replace concatenation with a variant map or inline literal classes.
3. If external – add a narrow safelist entry (e.g., text-emerald-600) or a tight regex (bg-(red|green)-500).
4. Verify bundle size – run npx tailwindcss -o dist/output.css and grep -c '\\.bg-' dist/output.css before and after changes.
5. Check linting – enable eslint-plugin-tailwindcss rule no-custom-classname to catch any remaining dynamic patterns.
6. Observe cache behavior – modify a safelist entry vs. a template file and note rebuild times with npm run build -- --verbose.

Final Thought

Use safelist only when you cannot touch the source of the class string. For all other cases, refactor to literal names; it keeps the codebase maintainable, the build cache efficient, and the linting ecosystem happy.

Do any of your runtime‑composed classes originate from content you cannot control (e.g., CMS fields or external HTML)? If so, a safelist is unavoidable.