WindiCSS plugin to generate safelist.txt files

With windicss-safelist-generator, you can generate a safelist.txt file for your theme based on a set of patterns.

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

Before you consider this plugin, we recommend reading WindiCSS's purgeable HTML docs. If this isn't an option—like when you need to generate WindiCSS classes with dynamic data from a CMS—this is for you.

WindiCSS's JIT mode scans your codebase for class names, and generates CSS based on what it finds. If a class name is not listed explicitly, like text-${error ? 'red' : 'green'}-500, WindiCSS won't discover it. To ensure these utilities are generated, you can maintain a file that lists them explicitly, like a safelist.txt file in the root of your project.

text-red-100
text-red-200

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

Maintaining this list can become cumbersome, because whenever you update your theme you need to update the safelist. That's why we created windicss-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 windicss-safelist-generator

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

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

We recommend adding safelist.txt to your .gitignore file, since it's an artifact that gets generated whenever WindiCSS generates CSS.

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('windicss-safelist-generator')({
      path: 'resources/css/safelist.txt',
      patterns: [
        // …
      ],
    }),
  ],
};

patterns

The patterns to generate the list from.

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

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

List of all available tokens can be found here.

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-{gap} → {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.