Tailwind Purge Content settings

A typical stylesheet for a Hyvä Theme is about 100kb (that’s ~17kb over the wire through HTTP compression).

This is because Tailwind only compiles the CSS actually used within a theme.

Because Tailwind needs to know which classes are used, we need to point the build script to the directories where our .phtml files are located. Typically, that would be app/design/frontend/Acme/default/templates/.

If you have .phtml files with Tailwind CSS classes in app/code or vendor/, these directories have to be included in your tailwind configuration, too.

Hyvä 1.1.14 and newer

Hyvä 1.1.15

Since release 1.1.15 of the hyva-themes/magento2-theme-module the file app/etc/hyva-themes.json is used to automatically include relevant modules in the purge content paths configuration.
The file regenerated automatically each time a module is enabled or disabled.

If necessary, it can be manually generated, too, using the command

bin/magento hyva:config:generate

Once a module is included in the list, it's templates will automatically be scanned for Tailwind CSS classes.

Hyvä 1.1.14

Since release 1.1.14 of the hyva-themes/magento2-theme-module the file app/etc/hyva-themes.json is used to automatically include relevant modules in the purge content paths configuration. The configuration file has to be regenerated each time a Hyvä compatibility module is installed or removed.

bin/magento hyva:config:generate

Once a module is included in the list, it's templates will automatically be scanned for Tailwind CSS classes.

Hyvä 1.1.13 and before

Themes up to Hyvä release 1.1.13 have to ensure all classes are found by including all relevant paths manually in the theme purge content configuration.
Alternatively, we recommend upgrading the hyva-themes/magento2-theme-module to 1.1.14 or newer and using the automatic tailwind purge content config merging.

Otherwise, manually add the module paths to the themes purge content configuration as described below under Purge Content Details.

Purge Content Details

The purging configuration can be found in your themes tailwind.config.js file, for example app/design/frontend/Acme/default/web/tailwind/tailwind.config.js.

Tailwind v2 vs. v3

The structure of the content settings changed with Tailwind v3.
Since then, the content property is specified on the top level of the module.exports. The purge property is no longer used.
Check out the Tailwind v3 documentation for details.
Be aware which version of Tailwind is used in your theme when adjusting the configuration!

Note that the configuration is not limited to .phtml templates. For example, layout XMl files might reference Tailwindcss classes, too, and can also be included in the content configuration.

Tailwind v2 purge config example

module.exports = {
  ...
  purge: {
    content: [
      // this theme's phtml files
      '../../**/*.phtml',
      // parent theme in vendor/
      '../../../../../../../vendor/hyva-themes/magento2-default-theme/**/*.phtml',
      // hyva theme-module templates (only necessary for Hyva themes before 1.1.15)
      '../../../../../../../vendor/hyva-themes/magento2-theme-module/src/view/frontend/templates/**/*.phtml',
      // app/code phtml files (if you need tailwind classes from app/code modules)
      //'../../../../../../../app/code/**/*.phtml',
      // react app src files (if Hyvä Checkout is installed in app/code)
      //'../../../../../../../app/code/**/src/**/*.jsx',
      // react app src files in vendor (If Hyvä Checkout is installed in vendor)
      //'../../../../../../../vendor/hyva-themes/magento2-hyva-react-checkout/src/reactapp/src/**/*.jsx',
      //'../../../../../../../vendor/hyva-themes/magento2-hyva-react-checkout/src/view/frontend/templates/react-container.phtml',
      // widget block classes from app/code
      //'../../../../../../../app/code/**/Block/Widget/**/*.php'
    ]
  }
}

Tailwind v3 config example

module.exports = {
  ...
  content: [
    // this theme's phtml files
    '../../**/*.phtml',
    // parent theme in vendor/
    '../../../../../../../vendor/hyva-themes/magento2-default-theme/**/*.phtml',
    // hyva theme-module templates
    '../../../../../../../vendor/hyva-themes/magento2-theme-module/src/view/frontend/templates/**/*.phtml',
  ]
}

Please check out this excellent blog post on the topic of programmatically built tailwind class names and the purge process by Luke Collymore for more useful information: https://www.develodesign.co.uk/learn/hyva-missing-sites-in-production-build

Advanced Configuration

Rather than add an array of directories for Tailwind to look up the classes used in your theme, you could use a function to dynamically add the templates you wish to include.

This can be useful if you wish for your theme to inherit from the Hyva/default theme, but not to check for any templates in it which you have overridden in your own theme.

With such an approach your site will receive updates from the Hyva/default theme when you upgrade it and no unused Tailwind CSS classes will be added.

// The below would be based on Hyva/default but updated to reflect your theme name
.
├── composer.json
├── registration.php
├── theme.xml
└── web/
    ├── css/
    └── tailwind/

Below is an example of how you could customise your theme’s web/tailwind/tailwind.config.js file for such a scenario.

const { colors } = require('tailwindcss/defaultTheme')
const path = require('path')
const fs = require('fs')

/**
 * Finds and lists all files in a directory with a specific extension
 * https://gist.github.com/victorsollozzo/4134793
 * @return Array
 */
function recFindByExt(base,ext, files,result) {
    files = files || fs.readdirSync(base)
    result = result || []

    files.forEach(
        function (file) {
            const newbase = path.join(base,file);
            if (fs.statSync(newbase).isDirectory()) {
                result = recFindByExt(newbase, ext, fs.readdirSync(newbase), result)
            } else {
                if (file.substr(-1*(ext.length+1)) == '.' + ext) {
                    result.push(newbase)
                }
            }
        }
    )
    return result
}

/**
 * Returns an array of all files to be used in tailwind purge.content
 */
const purgeContent = () => {
    // Add any sub-directories you wish to be excluded by Tailwind when checking 
    // the hyva-default theme.
    // For example you may have removed Magento_Review from your store, and therefore
    // do not wish for Tailwind to generate any CSS for it.
    const EXCLUDE_FROM_PARENT = []; // e.g. ['Magento_Review']

    // Declare array to stores all paths for hyvaDefault theme's phtml files
    let hyvaDefault = recFindByExt('../../../../../../../vendor/hyva-themes/magento2-default-theme/', 'phtml');

    // Declare array to stores all paths for your current theme's phtml files
    let currentTheme = recFindByExt('../../','phtml');

    // Filter the array of templates from hyva-default to remove any templates overridden in your theme.
    // A similar filter can be used on other parent theme's if you have a
    // multi-store Magento install using a different theme structure.
    hyvaDefault = hyvaDefault.filter(function(item) {
        let isAllowed = true;

        for (const key in this) {
            if (item.includes(this[key].replace(/\.\.\//g, ''))) {
                isAllowed = false;
            }
        }

        return isAllowed;
    }, currentTheme.concat(EXCLUDE_FROM_PARENT));

    return currentTheme.concat(hyvaDefault);
}

module.exports = {
    // ...omitted code
    content: purgeContent()
}

The above is only an example. You may need to customise it further to suit your own theme, for instance customising the purgeContent() function to include files from Magento’s app/code directory or .jsx files etc.

Tailwind v3 vs v2

In the above example the paths array is assigned to module.exports.content. This is correct for Tailwind v3 (themes based on Hyvä 1.2.x and above).
For themes based on Tailwind v2 the paths have to be set as module.exports.purge.content.