PurifyCSS

A function that takes content (HTML/JS/PHP/etc) and CSS, and returns only the used CSS.
PurifyCSS does not modify the original CSS files. You can write to a new file, like minification.
If your application is using a CSS framework, this is especially useful as many selectors are often unused.

Potential reduction

• Bootstrap file: ~140k
• App using ~40% of selectors.
• Minified: ~117k
• Purified + Minified: ~35k

Usage

Standalone

Installation

npm i -D purify-css

import purify from "purify-css"
const purify = require("purify-css")

let content = ""
let css = ""
let options = {
    output: "filepath/output.css"
}
purify(content, css, options)

Build Time

• Grunt
• Gulp
• Webpack

CLI Usage

$ npm install -g purify-css

$ purifycss -h

purifycss   [option]
Options:
  -m, --min        Minify CSS                         [boolean] [default: false]
  -o, --out        Filepath to write purified css to                    [string]
  -i, --info       Logs info on how much css was removed
                                                      [boolean] [default: false]
  -r, --rejected   Logs the CSS rules that were removed
                                                      [boolean] [default: false]
  -w, --whitelist  List of classes that should not be removed
                                                           [array] [default: []]
  -h, --help       Show help                                           [boolean]
  -v, --version    Show version number                                 [boolean]

How it works

Used selector detection

Statically analyzes your code to pick up which selectors are used.
But will it catch all of the cases?

Let's start off simple.

Detecting the use of:

button-active

  
  
  
click

  // javascript
  // Anytime your class name is together in your files, it will find it.
  $(button).addClass('button-active');

Now let's get crazy.

Detecting the use of:

button-active

  // Can detect if class is split.
  var half = 'button-';
  $(button).addClass(half + 'active');

  // Can detect if class is joined.
  var dynamicClass = ['button', 'active'].join('-');
  $(button).addClass(dynamicClass);
  // Can detect various more ways, including all Javascript frameworks.
  // A React example.
  var classes = classNames({
    'button-active': this.state.buttonActive
  });
  return (
    Submit;
  );

Examples

Example with source strings

var content = ' Login ';
var css = '.button-active { color: green; }   .unused-class { display: block; }';

console.log(purify(content, css));

logs out:

.button-active { color: green; }

Example with glob file patterns + writing to a file

var content = ['**/src/js/*.js', '**/src/html/*.html'];
var css = ['**/src/css/*.css'];

var options = {
  // Will write purified CSS to this file.
  output: './dist/purified.css'
};
purify(content, css, options);

Example with both glob file patterns and source strings + minify + logging rejected selectors

var content = ['**/src/js/*.js', '**/src/html/*.html'];
var css = '.button-active { color: green; } .unused-class { display: block; }';

var options = {
  output: './dist/purified.css',
  // Will minify CSS code in addition to purify.
  minify: true,
  // Logs out removed selectors.
  rejected: true
};
purify(content, css, options);

logs out:

.unused-class

Example with callback

var content = ['**/src/js/*.js', '**/src/html/*.html'];
var css = ['**/src/css/*.css'];

purify(content, css, function (purifiedResult) {
  console.log(purifiedResult);
});

Example with callback + options

var content = ['**/src/js/*.js', '**/src/html/*.html'];
var css = ['**/src/css/*.css'];

var options = {
  minify: true
};
purify(content, css, options, function (purifiedAndMinifiedResult) {
  console.log(purifiedAndMinifiedResult);
});

API in depth

// Four possible arguments.
purify(content, css, options, callback);

The

content

argument

Type:

Array

or

String

Array

String

The

css

argument

Type:

Array

or

String

Array

String

The (optional)

options

argument

Type:

Object

Properties of options object:

• minify:

  Set to

  true

  to minify. Default:

  false

  .

• output:

  Filepath to write purified CSS to. Returns raw string if

  false

  . Default:

  false

  .

• info:

  Logs info on how much CSS was removed if

  true

  . Default:

  false

  .

• rejected:

  Logs the CSS rules that were removed if

  true

  . Default:

  false

  .

• whitelist

  Array of selectors to always leave in. Ex.

  ['button-active', '*modal*']

  this will leave any selector that includes

  modal

  in it and selectors that match

  button-active

  . (wrapping the string with *'s, leaves all selectors that include it)

The (optional)

callback

argument

Type:

Function

A function that will receive the purified CSS as it's argument.

Example of callback use

purify(content, css, options, function(purifiedCSS){
  console.log(purifiedCSS, ' is the result of purify');
});

Example of callback without options

purify(content, css, function(purifiedCSS){
  console.log('callback without options and received', purifiedCSS);
});

Example CLI Usage

$ purifycss src/css/main.css src/css/bootstrap.css src/js/main.js --min --info --out src/dist/index.css

This will concat both

main.css

bootstrap.css

main.js

dist/index.css

The

--min

The

--info

The CLI currently does not support file patterns.