purifycss/purifycss

Name: purifycss

Owner: PurifyCSS

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

Created: 2015-05-26 02:42:17.0

Updated: 2018-01-18 16:13:49.0

Pushed: 2017-12-25 09:21:09.0

Homepage:

Size: 385

Language: JavaScript

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

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

i -D purify-css

avascript
rt purifycss from "purify-css"
t purifycss = require("purify-css")

content = ""
css = ""
options = {
output: "filepath/output.css"

fy(content, css, options)

Build Time

• Grunt
• Gulp
• Webpack

CLI Usage

m install -g purify-css

rifycss -h

fycss <css> <content> [option]

ons:
, --min        Minify CSS                         [boolean] [default: false]
, --out        Filepath to write purified css to                    [string]
, --info       Logs info on how much css was removed
                                                  [boolean] [default: false]
, --rejected   Logs the CSS rules that were removed
                                                  [boolean] [default: false]
, --whitelist  List of classes that should not be removed
                                                       [array] [default: []]
, --help       Show help                                           [boolean]
, --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

-- html -->
-- class directly on element -->
iv class="button-active">click</div>

javascript
 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.
r half = 'button-';
button).addClass(half + 'active');

 Can detect if class is joined.
r dynamicClass = ['button', 'active'].join('-');
button).addClass(dynamicClass);

 Can detect various more ways, including all Javascript frameworks.
 A React example.
r classes = classNames({
'button-active': this.state.buttonActive
;

turn (
<button className={classes}>Submit</button>;

Examples

Example with source strings

content = '<button class="button-active"> Login </button>';
css = '.button-active { color: green; }   .unused-class { display: block; }';

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

logs out:

ton-active { color: green; }

Example with glob file patterns + writing to a file

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

options = {
 Will write purified CSS to this file.
tput: './dist/purified.css'


fy(content, css, options);

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

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

options = {
tput: './dist/purified.css',

 Will minify CSS code in addition to purify.
nify: true,

 Logs out removed selectors.
jected: true


fy(content, css, options);

logs out:

sed-class

Example with callback

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

fy(content, css, function (purifiedResult) {
nsole.log(purifiedResult);

Example with callback + options

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

options = {
nify: true


fy(content, css, options, function (purifiedAndMinifiedResult) {
nsole.log(purifiedAndMinifiedResult);

API in depth

our possible arguments.
fy(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

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

Example of callback without options

fy(content, css, function(purifiedCSS){
nsole.log('callback without options and received', purifiedCSS);

Example CLI Usage

rifycss 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.