Fix Tailwind CSS missing classes in WordPress content by updating the purge conf

by

Summary

Tailwind classes inside WordPress page content are omitted from the production CSS because the build process only scans template files, not the dynamic content stored in the database. To include those classes, the purge (or content) configuration must point to the editor output as well.

Root Cause

  • Tailwind’s content scanning looks at files on disk (e.g., *.php, *.js, *.html).
  • WordPress stores page/block markup in the database, not in source files.
  • The default tailwind.config.js does not include the wp-content HTML generated by the block editor, so the classes never get compiled into output.css.

Why This Happens in Real Systems

  • Static analysis: Tailwind’s JIT compiler works by statically analyzing source files; it cannot guess classes that will appear only at runtime.
  • Separation of concerns: Themes often assume that only theme files need scanning, overlooking dynamic content.
  • Performance safety: Ignoring unknown classes keeps the final bundle small, which is why Tailwind defaults to a restrictive content list.

Real-World Impact

  • Missing UI styles: Editors see raw HTML without any Tailwind styling, breaking design consistency.
  • Developer confusion: The CDN works, leading teams to mistakenly think the problem is the build step.
  • Potential for production bugs: Relying on the CDN in production introduces larger payloads and security warnings.

Example or Code (if necessary and relevant)

// tailwind.config.js
module.exports = {
  content: [
    "./*.php",
    "./**/*.php",
    "./assets/js/**/*.js",
    // Add the built HTML saved by the editor
    "./wp-content/**/*.html",
    // Or use a wildcard that captures the DB‑rendered output via a WP filter
    "./**/*.php",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
};

How Senior Engineers Fix It

  • Extend the content array to include paths that represent the rendered block markup (e.g., a temporary template-parts folder or a custom endpoint that outputs saved content).
  • Leverage the safelist option to explicitly whitelist classes that appear only in the editor.
  • Create a build step that extracts post content to static files before running Tailwind, ensuring those classes are seen during compilation.
  • Integrate with WP’s the_content filter to append a hidden <script type="text/tailwindcss"> block containing the raw classes, then run the JIT compiler in watch mode during development.
  • Validate the final bundle with tools like purgecss to confirm no required classes are stripped.

Why Juniors Miss It

  • They often assume Tailwind’s JIT automatically “knows” about every class used in the site.
  • They focus on the theme’s PHP files and overlook that WordPress stores content in the DB, which isn’t part of the static file tree.
  • They may copy‑paste solutions (e.g., CDN) without understanding the underlying build pipeline, leading to temporary fixes instead of a proper configuration.

Leave a Comment