# PurifyCSS [![Travis](https://img.shields.io/travis/purifycss/purifycss/master.svg)]() [![npm](https://img.shields.io/npm/dm/purify-css.svg)]() [![David](https://img.shields.io/david/purifycss/purifycss.svg)]() ![Join the chat at https://gitter.im/purifycss/purifycss](https://badges.gitter.im/purifycss/purifycss.svg) 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](https://github.com/twbs/bootstrap) file: ~140k * App using ~40% of selectors. * Minified: ~117k * Purified + Minified: **~35k** ## Usage ### Standalone Installation ```bash npm i -D purify-css ``` ```javascript import purifycss from "purify-css" const purifycss = require("purify-css") let content = "" let css = "" let options = { output: "filepath/output.css" } purify(content, css, options) ``` ### Build Time - [Grunt](https://github.com/purifycss/grunt-purifycss) - [Gulp](https://github.com/purifycss/gulp-purifycss) - [Webpack](https://github.com/purifycss/purifycss-webpack-plugin) ### 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` ``` html

click

``` ``` 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` ``` javascript // 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 ( ; ); ``` ### Examples ##### Example with source strings ```js var content = ''; var css = '.button-active { color: green; } .unused-class { display: block; }'; console.log(purify(content, css)); ``` logs out: ``` .button-active { color: green; } ``` ##### Example with [glob](https://github.com/isaacs/node-glob) file patterns + writing to a file ```js 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](https://github.com/isaacs/node-glob) file patterns and source strings + minify + logging rejected selectors ```js 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 ```js 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 ```js 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 ```javascript // Four possible arguments. purify(content, css, options, callback); ``` ##### The `content` argument ##### Type: `Array` or `String` **`Array`** of [glob](https://github.com/isaacs/node-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](https://github.com/isaacs/node-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 ``` javascript purify(content, css, options, function(purifiedCSS){ console.log(purifiedCSS, ' is the result of purify'); }); ``` ##### Example of callback without options ``` javascript 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.

	Stars	Issues	Version	Updated	Created
cssnano	4,661	92	7.0.3	7 days ago	9 years ago
foundation	20	1	4.2.1-1	11 years ago	11 years ago
gulp-clean-css	649	11	4.3.0	4 years ago	10 years ago
purgecss	7,703	52	6.0.0	3 months ago	7 years ago
purifycss			1.2.6	7 years ago	8 years ago

cssnano vs foundation vs gulp-clean-css vs purgecss vs purifycss

Downloads in past1 Month3 Months6 Months1 Year2 Years5 YearsAll time

Stats

Popular Searches

Sick of boring JavaScript newsletters?

Downloads in past