tailwind-safelist-generator

Tailwind plugin to generate safelist.txt files

module.exports = {
  plugins: [
    require('tailwind-safelist-generator')({
      path: 'safelist.txt',
      patterns: [
        'text-{colors}',
        'border-{borderWidth}',
        '{screens}:gap-{spacing},
      ],
    }),
  ],
};

As Tailwind suggest, write purgeable HTML when possible. However, sometimes purgeable HTML isn't an option, like when you need to generate Tailwind classes with data from a CMS.

To ensure classes that don't appear in your codebase don't get purged, you can maintain a plain .txt listing them so Tailwind will pick them up and generate them.

For example, a safelist.txt file in the root of your project that get's included in Tailwinds purge option.

text-red-100
text-red-200

module.exports = {
  mode: 'jit'
  purge: [
    './**/*.html',
    './safelist.txt',
  ],
};

Maintaining this list can be cumbersome, because whenever you update your theme, you need to update the list. That's why we created tailwind-safelist-generator, so you can declare a set of classes you don't want to purge that stay in sync with your theme.

Support us

We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products.

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall.

Installation

You can install the package via npm or yarn:

npm i tailwind-safelist-generator

Next, register the plugin in your Tailwind configuration file and specify the patterns you want to safelist. Don't forget to add ./safelist.txt to Tailwind's purge option.

module.exports = {
  mode: 'jit'
  purge: [
    './**/*.html',
    './safelist.txt',
  ],
  plugins: [
    require('tailwind-safelist-generator')({
      patterns: [
        'text-{colors}',
        'border-{borderWidth}',
        '{screens}:gap-{spacing},
      ],
    }),
  ],
};

Options

path

The path and filename where safelist.txt will be generated. By default, it's placed in the root of your project.

module.exports = {
  plugins: [
    require('tailwind-safelist-generator')({
      path: 'resources/css/safelist.txt',
      patterns: [
        // …
      ],
    }),
  ],
};

patterns

The patterns to generate the list from.

module.exports = {
  plugins: [
    require('tailwind-safelist-generator')({
      patterns: [
        'text-{color}',
        'border-{borderWidth}',
        '{screens}:gap-{spacing},
      ],
    }),
  ],
};

Each token wrapped in {} will be passed through Tailwind's theme() helper to retrieve all possible values. Then the plugin generates a list of all combinations.

text-{colors} → text-{red-100,red-200,…}

text-red-100
text-red-200

Using more than one token may generate a long list of combinations:

{screens}:gap-{spacing} → {sm,lg}:gap-{0,1,2,4}

sm:gap-0
sm:gap-1
sm:gap-2
sm:gap-4
md:gap-0
md:gap-1
md:gap-2
md:gap-4

Testing

Tests are written with Jest.

npm run test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Sebastian De Deyne
• All Contributors

License

The MIT License (MIT). Please see License File for more information.