Fixing Missing Tailwind Classes in Production Builds

The bug report is always some version of "the badge is grey on the live site but green locally." Tailwind generates CSS by scanning source files for class names as plain strings; anything it does not find is not in the stylesheet. That design is what keeps Tailwind output small — the subject of Keeping Tailwind CSS Output Small on Static Sites — and it is also why classes go missing: a class built from string fragments, a component in a folder the scanner skips, or a class that only appears in CMS content never makes it into the production CSS.

This guide works through missing classes on an Astro 5 marketing and docs site using Tailwind 4, after a redesign shipped with 23 visibly broken elements on production. It shows how to find every missing class, the four causes and their fixes, and a CI check that compares the classes used in the built HTML with the classes present in the CSS. It belongs to CSS and JavaScript Asset Optimization.

Step 1: Find Every Missing Class

The reliable test compares what the HTML uses with what the CSS defines, on the production build:

// scripts/check-tailwind-classes.mjs
import { glob } from 'glob';
import fs from 'node:fs/promises';
const css = (await Promise.all((await glob('dist/_astro/*.css')).map((f) => fs.readFile(f, 'utf8')))).join('\n');
const defined = new Set([...css.matchAll(/\.((?:\\.|[\w-])+)/g)].map((m) => m[1].replace(/\\(.)/g, '$1')));
const used = new Map();
for (const f of await glob('dist/**/*.html')) {
  const html = await fs.readFile(f, 'utf8');
  for (const [, cls] of html.matchAll(/class="([^"]+)"/g))
    for (const c of cls.split(/\s+/)) if (c && !defined.has(c)) used.set(c, (used.get(c) ?? 0) + 1);
}
console.log([...used].sort((a, b) => b[1] - a[1]).slice(0, 50));

This reports class names used in the HTML with no matching selector in the CSS. It includes some false positives — classes used only as JavaScript hooks, or styled by component-scoped CSS — which go into an allow-list once. On this site it found 41 missing Tailwind classes across 23 visible elements.

Cause 1: Class Names Built From Fragments

The redesign's status badge chose its colour like this:

<span class={`bg-${color}-100 text-${color}-800`}>{label}</span>

The strings bg-green-100 and text-green-800 never appear in the source, so Tailwind never generates them. In development they had worked because the old design used those exact classes elsewhere — until the redesign removed the other uses. The fix is a lookup with full class names:

const STATUS = {
  stable: 'bg-green-100 text-green-800',
  beta: 'bg-amber-100 text-amber-900',
  deprecated: 'bg-red-100 text-red-800',
} as const;
<span class={STATUS[status]}>{label}</span>

Seventeen missing classes came from five components using this pattern. A lint rule (eslint-plugin-tailwindcss's no-custom-classname with a pattern for template literals, plus a simple grep in CI for `(bg|text|border)-\$\{) now flags fragment-built class names.

Cause 2: Markdown Content Outside the Sources

Tailwind 4 detects sources automatically, but it skips files ignored by .gitignore. The docs content was pulled from another repository into src/content/external/ at build time, and that folder was in .gitignore. Writers used Tailwind classes in that Markdown (<div class="grid md:grid-cols-2 gap-6">), which worked locally only when the same classes appeared elsewhere. An explicit source directive includes the folder regardless of .gitignore:

@import 'tailwindcss';
@source '../content/external';

Cause 3: A Shared Component Package

The site used a company design-system package from node_modules, whose components used Tailwind classes. Tailwind does not scan node_modules by default. Another @source directive pointing at the package's built files fixed it:

@source '../../node_modules/@acme/ui/dist';

Scanning the built output rather than the package's source keeps the scan fast and matches what actually ships.

Cause 4: Classes Chosen in the CMS

Landing pages came partly from a headless CMS, whose editors could pick a background colour for a section from a dropdown that stored class names (bg-indigo-50). Those strings never existed in any file at build time. Two options: generate a file from the CMS's allowed values during the build and add it as a source, or safelist them. Because the dropdown had a fixed list of eight values, a safelist in CSS was the simplest:

@source inline('bg-{indigo,emerald,amber,slate}-50');

Tailwind 4's @source inline() takes brace expansion, so one line covers the four used here. The CMS dropdown and this line are kept in sync by a test that fetches the CMS field's allowed values and checks each is generated.

Step 2: Make the Check Part of CI

The comparison script runs after every production build and fails on any missing class not in the allow-list. It takes about 3 seconds for 900 pages. Since it was added, it has caught six regressions, four of them fragment-built class names in new components.

Why the Dev Server Hid the Problem

All 41 classes had looked fine to the developers who wrote the redesign, which is what made the bug expensive. Three things in development mask missing classes. Tailwind's dev mode keeps generated classes across edits within a session, so a class that existed in an earlier version of a file stays in the stylesheet until the server restarts. Developers' local checkouts contained the external content folder from earlier builds, and some had it tracked in an old branch that was not gitignored, so automatic detection found it on their machines but not in CI. And the design-system package was linked locally with npm link for development, which placed its source inside the project tree where it was scanned — while the production build installed it normally into node_modules, where it was not.

The team's rule since then is that styling is reviewed on the preview deployment, built by CI from a clean checkout, never on a local dev server. The preview deployment comment on each pull request links to the pages the change touches, and the HTML-versus-CSS check runs against that same build before the comment is posted.

Dark Mode and Variant Classes

Variant-prefixed classes fail the same way and are harder to spot, because they only show in one state. A dark:bg-slate-800 assembled as `${dark ? 'dark:' : ''}bg-slate-800` generates only the light variant; the dark one appears missing only when a reader uses dark mode. The HTML-versus-CSS check covers variants too, because the full class name including its prefix appears in the HTML's class attribute and must match an escaped selector (.dark\:bg-slate-800) in the CSS. Four of the 41 missing classes were dark-mode variants that no developer had seen broken.

Measured Impact

Pitfalls & Rollback

• Building class names from fragments. Use full strings in a lookup.
• Fixing by safelisting everything. The stylesheet grows and the real cause remains.
• Trusting the dev server. Test on a clean production build.
• Content outside the sources. Add @source for external folders and packages.
• Rollback: each fix is a source directive or a component change; reverting one brings back only its missing classes, which the CI check will report.

Conclusion

Tailwind classes go missing in production because Tailwind only generates what it can read as full strings in scanned files. Replacing fragment-built names with lookups, adding source directives for external content and packages, and safelisting a short list of CMS values fixed 41 missing classes on this site, and comparing the built HTML with the built CSS in CI keeps new ones from shipping.

FAQ

Why do Tailwind classes work in development but not in production?

Tailwind generates CSS only for class names it finds as complete strings in the files it scans. In development the dev server may have seen a class in another file, or an old build cache kept it. In production the clean build scans only the configured sources, so a class built by string concatenation, or used only in a file outside the sources, is not generated.

How do I use dynamic class names with Tailwind?

Write every possible class name in full somewhere Tailwind scans, usually in a lookup object such as a map from a status to text-green-700 or text-red-700, and select from it at runtime. Never build class names from fragments like text- plus a colour variable, because the full name never appears in the source.

Does Tailwind scan Markdown and content files?

Only if they are included in the content sources. In Tailwind 4, automatic source detection scans the project but ignores files listed in gitignore and some large or binary files, and content stored outside the project, such as a CMS, is never scanned. Add explicit source directives for Markdown folders and for any content that arrives at build time.

Is a safelist a good fix for missing classes?

For a small set of classes that genuinely cannot appear in source, such as classes chosen by editors in a CMS, yes. As a general fix it is a trap, because it grows without limit and adds unused CSS. Prefer making class names appear in scanned files, and keep the safelist short and documented.

Related

• Parent: CSS and JavaScript Asset Optimization — CSS and JS weight on static sites.
• Keeping Tailwind CSS Output Small on Static Sites — the other side of the same scanning model.
• Tailwind v4 in Astro Without PostCSS Plugins — the setup used here.
• Purging Unused CSS with Tailwind and Lightning CSS — removing CSS that is not used.
• Visual Regression Testing on Preview Deploys — catching broken styling visually.