Merge branch 'master' into feature/keyframes_refactor

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+# v0.18.0 - 2018-01-05
+
+* Change default extractor regex, fixing https://github.com/FullHuman/purgecss/issues/37
+* Update dependencies
+* Use files property in package.json: importing only necessary files.
+
 # v0.16.0 - 2017-12-18
 
 * `keyframes` option set to `false` by default, `keyframes: true` causing issue with bootstrap https://github.com/FullHuman/purgecss/issues/33

docs/README.md

@@ -0,0 +1,172 @@
+# Purgecss
+
+![](https://travis-ci.org/FullHuman/purgecss.svg?branch=master) ![](https://circleci.com/gh/FullHuman/purgecss/tree/master.svg?style=shield) ![](https://david-dm.org/fullhuman/purgecss/status.svg) ![](https://david-dm.org/fullhuman/purgecss/dev-status.svg) ![](https://api.codacy.com/project/badge/Grade/2f2f3fb0a5c541beab2018483e62a828) ![](https://api.codacy.com/project/badge/Coverage/2f2f3fb0a5c541beab2018483e62a828) ![](https://img.shields.io/badge/styled_with-prettier-ff69b4.svg) ![](https://img.shields.io/github/license/fullhuman/purgecss.svg)
+
+---
+
+Purgecss is a tool to remove unused css. It can be used as part of your development workflow. Purgecss comes with a Javascript API, a CLI and plugins for popular build tools.
+
+Here are a couple of ways to use Purgecss:
+
+* [CLI](#cli)
+* [Javascript API](#javascript-api)
+* [Webpack](#webpack)
+* [Gulp](#gulp)
+* [Rollup](#rollup)
+
+## CLI
+
+You can install the CLI in two ways. By installing purgecss globaly or using npx.
+
+### Install globally
+
+```
+npm i -g purgecss
+```
+
+You can then use it with
+
+```
+purgecss --css <css> --content <content> [option]
+```
+
+### Using npx
+
+[npx](https://www.npmjs.com/package/npx)[^1] allows you to run cli locally without installing the package globally.
+
+You can install purgecss as a dev dependency
+
+```
+npm i -D purgecss
+```
+
+You can then use it with
+
+```
+npx purgecss --css <css> --content <content> [option]
+```
+
+## Javascript API
+
+Start by installing Purgecss as a development dependency.
+
+```
+npm i -D purgecss
+```
+
+You can then use purgecss inside a javascript file.
+
+### ES6 with import
+
+```js
+import Purgecss from 'purgecss'
+const purgeCss = new Purgecss({
+  content: ['**/*.html'],
+  css: ['**/*.css']
+})
+const purgecssResult = purgecss.purge()
+```
+
+### ES5 with require
+
+```js
+var Purgecss = require('purgecss').default
+var purgecss = new Purgecss({
+  content: ['**/*.html'],
+  css: ['**/*.css']
+})
+var purgecssResult = purgecss.purge()
+```
+
+## Webpack
+
+Start by installing the plugin as a dev dependency:
+
+```
+npm i -D purgecss-webpack-plugin
+```
+
+```js
+const path = require('path')
+const glob = require('glob')
+const ExtractTextPlugin = require('extract-text-webpack-plugin')
+const PurgecssPlugin = require('purgecss-webpack-plugin')
+
+const PATHS = {
+  src: path.join(__dirname, 'src')
+}
+
+module.exports = {
+  entry: './src/index.js',
+  output: {
+    filename: 'bundle.js',
+    path: path.join(__dirname, 'dist')
+  },
+  module: {
+    rules: [
+      {
+        test: /\.css$/,
+        use: ExtractTextPlugin.extract({
+          fallback: 'style-loader',
+          use: 'css-loader?sourceMap'
+        })
+      }
+    ]
+  },
+  plugins: [
+    new ExtractTextPlugin('[name].css?[hash]'),
+    new PurgecssPlugin({
+      paths: glob.sync(`${PATHS.src}/*`)
+    })
+  ]
+}
+```
+
+## Gulp
+
+Start by installing the gulp plugin as a dev dependency:
+
+```
+npm i -D gulp-purgecss
+```
+
+```js
+const gulp = require('gulp')
+const purgecss = require('gulp-purgecss')
+
+gulp.task('purgecss', () => {
+  return gulp
+    .src('src/**/*.css')
+    .pipe(
+      purgecss({
+        content: ['src/**/*.html']
+      })
+    )
+    .pipe(gulp.dest('build/css'))
+})
+```
+
+## Rollup
+
+Start by installing the rollup plugin as a dev dependency:
+
+```
+npm i -D rollup-plugin-purgecss
+```
+
+```js
+import { rollup } from 'rollup'
+import purgecss from 'rollup-plugin-purgecss'
+
+rollup({
+  entry: 'main.js',
+  plugins: [
+    purgecss({
+      content: ['index.html']
+    })
+  ]
+})
+```
+
+[^1]: If you want to use npx, npm 5.2.0+ must be installed.
+

docs/SUMMARY.md

@@ -0,0 +1,13 @@
+# Summary
+
+* [Introduction](README.md)
+* [Configuration](configuration.md)
+* [CLI](cli.md)
+* [Javascript API](javascript-api.md)
+* [With Webpack](with-webpack.md)
+* [With Gulp](with-gulp.md)
+* [With Rollup](with-rollup.md)
+* [Whitelisting](whitelisting.md)
+* [Extractors](extractors.md)
+* [Comparison](comparison.md)
+

docs/cli.md

@@ -0,0 +1,71 @@
+# CLI
+
+Purgecss is available via a CLI. You can use the CLI by itself or with a configuration file.
+
+## Installation
+
+```
+npm i -g purgecss
+```
+
+## Usage
+
+To see the available options for the CLI: `purgecss --help`
+
+```
+purgecss --css <css> --content <content> [option]
+
+Options:
+  --con, --content  glob of content files                                [array]
+  -c, --config      configuration file                                  [string]
+  -o, --out         Filepath directory to write purified css files to   [string]
+  -w, --whitelist   List of classes that should not be removed
+                                                           [array] [default: []]
+  -h, --help        Show help                                          [boolean]
+  -v, --version     Show version number                                [boolean]
+```
+
+The options available through the CLI are similar to the ones available with a configuration file. You can also use the CLI with a configuration file.
+
+### --css
+
+```
+purgecss --css css/app.css css/palette.css --content src/index.html
+```
+
+### --content
+
+You can specified the content with an array of filename or [globs](https://github.com/isaacs/node-glob/blob/master/README.md#glob-primer) that should be analyized by purgecss. The files can be html, pug, blade, ... files.
+
+```
+purgecss --css css/app.css --content src/index.html src/**/*.js
+```
+
+### --config
+
+You can use the CLI with a [configuration file](/configuration.md). Use the `--config` or `-c` with the path to the config file.
+
+```
+purgecss --config ./purgecss.config.js
+```
+
+### --out
+
+By default, the CLI output the result in the console. If you wish to return the css as files, you need to specify the filepath directory to write the purified css files to.
+
+```
+purgecss --css css/app.css --content src/index.html src/**/*.js --out build/css/
+```
+
+### --whitelist
+
+If you wish to include a css selector that purgecss removes, you can whitelist it. It will tell purgecss not to remove it.
+
+```
+purgecss --css css/app.css --content src/index.html --whitelist classnameToWhitelist
+```
+
+## Example
+
+You can see an example in the examples folder of the purgecss repository [here](https://github.com/FullHuman/purgecss/tree/master/examples/cli/config-file).
+

docs/comparison.md

@@ -0,0 +1,33 @@
+# Comparison with other tools
+
+Purgecss is not the only tool to remove unused css. Below you will find a list of some of the tools available as well as a comparison with Purgecss.
+
+## Purifycss
+
+The biggest flaw with purifycss is its lack of modularity. It is also is biggest benefit, purifycss can work with any files, not just html or javascript. But purifycss works by looking at all the words in the files and comparing them with the selectors in the css. Every words is consider a selector, which means that a lot of selectors can be consider used because you have the selector name in a paragraph or somewhere in your files.
+
+Purgecss fixes this problem by providing the possibility to create an _extractor_. An extractor is a function that takes the content of a file and extract the list of css selectors in it. It allows a perfect removal of unused css. The extractor can used a parser that returns an ast and then looks through it to select the css selectors.
+
+That is the way `purge-from-html` works. You can specified which selectors you want to use for each types of files, and so, get the most accurate results. You can still use the default or the legacy extractor that will act the same way as purifycss.
+
+## Uncss
+
+As indicated in its Readme, Uncss works the following way:
+
+1. The HTML files are loaded by jsdom and JavaScript is executed.
+2. All the stylesheets are parsed by PostCSS.
+
+3. document.querySelector filters out selectors that are not found in the HTML files.
+
+4. The remaining rules are converted back to CSS.
+
+
+
+Because of the emulation of html, and the execution of javascript, uncss is effective at removing unused selectors from web application. But the emulation can have a cost in term of performance and practicality. Uncss works by emulating the html files. To remove unused css from pug template files, you will need to convert pug to html and then emulate the page inside jsdom and uncss will run `document.querySelector` on each selectors and step 4.
+
+Uncss by its design is probably the most accurate tool to remove css out of a simple web application at this moment if you do not use server side rendering.
+
+Purgecss does not have an extractor right now for javascript files. But because of its modularity, developers can create an extractor for specific framework \(vue, react, aurelia\) and files \(pug, ejs\) and get the most accurate result without the need of emulation.
+
+
+