Missing utility classes in production build: Tailwind content scanner

Sustainable Content Configuration Patterns

The most sustainable pattern to prevent missing utilities is to use folder-level globs targeting specific source directories, combined with a strict no-dynamic-class policy. Instead of listing every file or using a root-level glob that risks scanning node_modules, define paths relative to your source root.

Recommended Configuration (v3)

module.exports = {
  content: [
    './src/**/*.{html,js,ts,jsx,tsx}',
    './public/index.html',
  ],
  // ...
}

To avoid scanner blind spots without bloating the build, adhere to these rules:

• Avoid String Interpolation: The scanner does not execute code. text-${color}-600 will be purged. Use full class names: color === 'red' ? 'text-red-600' : 'text-blue-600'.
• Use Safelists for Dynamic Data: If classes are generated from a database or API, add them to the safelist array in your config to force their inclusion regardless of source scanning.
• Explicit Extension Lists: Always list every extension used in your project (e.g., .vue, .svelte, .jsx) to ensure the scanner doesn't skip non-standard files.

Transitioning from v3 to v4

The transition from the JavaScript-based tailwind.config.js (v3) to the CSS-first @source directive (v4) shifts the risk from configuration oversight to directive placement.

• v3 Risk: Forgetting to add a new directory to the JS array during a project restructure.
• v4 Risk: Misplacing @source directives or relying on default detection that may not cover non-standard directory structures in complex monorepos.

While v4 aims for more automatic detection, explicit @source paths remain the primary way to guarantee coverage for files outside the immediate CSS dependency graph.

Verification Methods

The most reliable way to confirm utilities are present in production is to grep the compiled CSS bundle. This removes guesswork regarding whether the scanner worked.

Run the following command against your production build artifact:

grep "missing-class-name" ./dist/assets/index.css

If the class is missing, temporarily add it to the safelist. If the class then appears in production, the issue is confirmed as a scanner omission rather than a CSS cascade or specificity conflict.

Diagnostic Detail Needed: Are you using a monorepo structure where source files reside outside the root directory of the Tailwind installation?