purifycss

by purifycss

purifycss /purifycss

Remove unused CSS. Also works with single-page apps.

9.6K Stars 405 Forks Last release: over 3 years ago (v1.2.6) MIT License 304 Commits 8 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

PurifyCSS

Travis npm David Join the chat at https://gitter.im/purifycss/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

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
of glob file patterns to the files to search through for used classes (HTML, JS, PHP, ERB, Templates, anything that uses CSS selectors).

String
of content to look at for used classes.


The
css
argument
Type:
Array
or
String

Array
of glob file patterns to the CSS files you want to filter.

String
of CSS to purify.


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
and
bootstrap.css
and purify it by looking at what CSS selectors were used inside of
main.js
. It will then write the result to
dist/index.css

The

--min
flag minifies the result.

The

--info
flag will print this to stdout: ``` ________________________________________________ | | PurifyCSS has reduced the file size by ~ 33.8% | ________________________________________________
The CLI currently does not support file patterns.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.