Skip to content

Using Tailwind Classes in CMS Content without Browser Compilation

Deprecated

This page is deprecated since hyva-themes/magento2-cms-tailwind-jit was released. That module compiles Tailwind CSS for CMS content automatically on save.

If you are using the CMS Tailwind JIT module, do not follow the instructions on this page. This page is kept for sites that are not using the CMS Tailwind JIT compiler module.

Tailwind CSS uses PurgeCSS to compile only the classes that appear in your theme's template files. Classes used only in CMS blocks or pages are not scanned at build time, so they are stripped from the compiled styles.css. Without the CMS Tailwind JIT module, you need one of the following strategies to make those classes available.

Strategies

Define Custom CSS Classes for CMS Editors

Create named utility classes in CSS using @apply, then have content editors use those class names in CMS content instead of raw Tailwind utilities.

In CSS:

.huge {
    @apply text-5xl;
    @apply font-bold;
}

In the CMS block:

<span class="huge">HELLO</span>

Safelist Tailwind Classes in tailwind.config.js

Add specific class names to the safelist option in web/tailwind/tailwind.config.js to prevent them from being purged, even if they do not appear in any template file.

The following example protects a set of specific utility classes:

web/tailwind/tailwind.config.js
module.exports = {
  // ...
  purge: {
    content: [
      '../../**/*.phtml',
      './src/**/*.phtml'
    ],
    options: {
      // When using the Tailwind JIT compiler, only full class names work in the safelist.
      // When using the legacy AOT compiler, regular expressions are also supported.
      safelist: ['top-10', /^bg-opacity-/, /^-?[mp][trblxy]?-[4,8]$/, /^text-shadow/],
    },
  },
  // ...
}

Warning

Regular expressions as safelist values only work with the legacy AOT Tailwind CSS compiler. To be upgrade-safe for Tailwind CSS v3, specify a list of full class names instead of regex patterns.

Add a Safelist File to the Purge Content List

Instead of listing class names inside tailwind.config.js, create a plain text file (for example safelist.txt) containing all the class names you want to protect from purging. Then add the file path to the content section of tailwind.config.js so Tailwind scans it at build time.

Tip

The structure for specifying content sources and the safelist differs between Tailwind CSS v2 and v3. Use the correct format for the version installed in your theme. See the Tailwind CSS upgrade guide for details.