Tailwind plugin to generate safelist.txt files
With tailwind-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('tailwind-safelist-generator')({
path: 'safelist.txt',
patterns: [
'text-{colors}',
'border-{borderWidth}',
'{screens}:gap-{spacing},
],
}),
],
};
Before you consider this plugin, we recommend reading Tailwind's purgeable HTML docs. If this isn't an option—like when you need to generate Tailwind classes with dynamic data from a CMS—this is for you.
Tailwind'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, Tailwind 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 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},
],
}),
],
};
We recommend adding safelist.txt to your .gitignore file, since it's an artifact that gets generated whenever Tailwind 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('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
License
The MIT License (MIT). Please see License File for more information.
111 May 19, 2022
9 Dec 19, 2022
4 Oct 10, 2021
10 Oct 5, 2022
1 May 22, 2022
14 Jan 3, 2022
31 Dec 29, 2022
19 Dec 20, 2022
28 Oct 12, 2022
21.1k Dec 31, 2022
17 Aug 29, 2022
7 Aug 28, 2022
105 Jan 4, 2023
192 Nov 28, 2022
5 Jan 8, 2022
22 Dec 14, 2022
689 Dec 25, 2022
390 Nov 16, 2022
308 Dec 30, 2022
2 Sep 3, 2022
2.4k Jan 7, 2023
1.2k Dec 25, 2022
13.6k Jan 6, 2023
52 Nov 28, 2022
5.2k Jan 4, 2023
312 Dec 12, 2022
1 Oct 27, 2021
27 Jun 4, 2022
1.3k Jan 3, 2023