Jeff Ochoa

Whitelist selectors on Purgecss

Jeff Ochoa

PurgeCss is a node package that allows you to strip out all the unnecessary CSS code from your compiled files.

This package reads your CSS files and removes all the useless styles based on the selectors from your HTML views.

See the following basic implementation taken from the official documentation:

var Purgecss = require('purgecss')
var purgecss = new Purgecss({
content: ['**/*.html'],
css: ['**/*.css']
var purgecssResult = purgecss.purge()
view raw 1.js hosted with ❤ by GitHub

The pitfall

If you generate some CSS tags from your backend based on any response, you won’t get the expected output at the end of the process.

Let’s see the following example using PHP

<div class"alert alert-<?php echo $type; ?>" ><?php echo $message; ?></div>
// A prettier version using Laravel-Blade
<div class="aler alert-{{ $type }}">{{ $message }}</div>
view raw 2.php hosted with ❤ by GitHub

In this example, $type could return maybe “success” or “error” so at the end you’ll end up with alert-error or alert-success.

As PurgeCss doesn’t recognize the actual value of the variable, and the final CSS selector, is going to remove any style that you have defined for that selector:

.alert {
color: white;
.alert-error {
background: red;
.alert-success {
background: green;
view raw 3.css hosted with ❤ by GitHub

The output after using PurgeCss would be the following:

.alert { color: white; }

Whitelisting selectors

The good news is that PurgeCss allows specifying a list of selector you want to keep, even though if they aren’t present in your HTML files

const purgecss = new Purgecss({
content: [], // content
css: [], // css
whitelist: ['alert-success', 'alert-success']
view raw 4.js hosted with ❤ by GitHub

Even better! You can use a regular expression to keep any selector that matches the given pattern, for instance:

const purgecss = new Purgecss({
content: [], // content
css: [], // css
whitelistPatterns: [/alert/]
view raw 5.js hosted with ❤ by GitHub

There is a third option that I don’t really like that much, which is adding a comment in your CSS above any selector to prevent PurgeCss from removing it:

/* purgecss ignore */
.alert-success {
background: green;
view raw 6.css hosted with ❤ by GitHub

As I said before, I’m not a big fan of this approach, but you can use the one you like the most, I won’t judge you for that.


If you use Laravel-mix, you can use the laravel-mix-purcss package developed by the team, to add a purgeCss() method to your “mix” pipeline:

const mix = require('laravel-mix');
// ...
mix.js('resources/js/app.js', 'public/js')
.sass('resources/sass/app.scss', 'public/css')
view raw 7.js hosted with ❤ by GitHub

The mix.purgeCss() method receives the same configuration object supported by the original purgeCss package, see Configuration - Purgecss

And in case you are wondering... Yes, you can use laravel-mix outside the Laravel framework, take a look at the docs here:

Wrapping up

PurgeCss is a powerful tool that allows you to keep your CSS files at the minimum, and with the right configuration, you can make your development process more flexible.


Jeff Ochoa

Subscribe to receive updates in your mail inbox