/\ \  __/\ \/\ \      __/\ \__       /\_ \   __        /\ \__
\ \ \/\ \ \ \ \ \___ /\_\ \ ,_\    __\//\ \ /\_\    ___\ \ ,_\ By: Qodesmith
 \ \ \ \ \ \ \ \  _ `\/\ \ \ \/  /'__`\\ \ \\/\ \  /',__\ \ \/  /'__`\/\`'__\
  \ \ \_/ \_\ \ \ \ \ \ \ \ \ \_/\  __/ \_\ \\ \ \/\__, `\ \ \_/\  __/\ \ \/
   \ `\___x___/\ \_\ \_\ \_\ \__\ \____\/\____\ \_\/\____/\ \__\ \____\\ \_\
    '\/__//__/  \/_/\/_/\/_/\/__/\/____/\/____/\/_/\/___/  \/__/\/____/ \/_/

Purgecss Whitelister

Create whitelists dynamically to include your 3rd party library styles! Supports css, sass, and less.

Why this package?

While rebuilding my personal site in React and using webpack + purgecss-webpack-plugin, I noticed that my 3rd party library, Typer.js (it's really cool - it types things out on the screen like a typewriter), had its styles stripped from the bundle. While it wasn't that big a deal to type out the few class names into a whitelist array, what if that list was huge? What if it was yuuuge? I needed a way to dynamically generate a whitelist of selectors. Boom. purgecss-whitelister was born.

Installation

Via npm:

1npm i purgecss-whitelister

Usage

purgecss-whitelister is meant to extract all the selectors used in a file and create an array of names for whitelisting. Works with css, sass, and less! This is very handy when you have a 3rd party library that you don't want annihilated from your bundle.

Pass either a string, a globby string, or an array of either, representing the location(s) of the file(s) you want to completely whitelist.

NOTE: purgecss-whitelister will internally ignore any files that don't have the following extensions: css, sass, scss, less, or pcss.

NOTE: Use the pcss extension with caution. It may or may not work. pcss is a PostCSS file extension but has no official documentation. It's been added to this tool for convenience but YMMV. If anyone has info on the pcss extension, I'm all ears.

1const { resolve } = require('path')
2const whitelister = require('purgecss-whitelister')
3
4// Example 1 - simple string
5whitelister('./relative/path/to/my/styles.css')
6
7// Example 2 - array of strings
8whitelister(['./styles1.css', './styles2.scss'])
9
10// Example 3 - globby strings
11whitelister('./3rd/party/library/*.less')
12
13// Example 4 - array of globby strings
14whitelister([
15  './node_modules/lib1/*.css',
16  './node_modules/lib2/*.scss',
17  './node_modules/lib3/*.less'
18])
19
20// Example 5 - ALL THE THINGS
21//
22whitelister('./node_modules/cool-library/styles/*.*')

Webpack Example

This is essentially what I'm using in my webpack.config.js file:

1const whitelister = require('purgecss-whitelister')
2const PurgecssPlugin = require('purgecss-webpack-plugin')
3const glob = require('glob-all')
4const { resolve } = require('path')
5
6const webpackConfig = {
7
8  // ...a whole buncha stuffs up here...
9
10  plugins: [
11    new PurgecssPlugin({
12      keyframes: false, // https://goo.gl/bACbDW
13      styleExtensions: ['.css'],
14      paths: glob.sync([
15        resolve(resolve(), 'src/**/*.js'),
16        resolve(resolve(), 'src/index.ejs')
17      ]),
18
19      // `whitelist` needed to ensure Typer classes stay in the bundle.
20      whitelist: whitelister('node_modules/typer-js/typer.css');,
21      extractors: [
22        {
23          // https://goo.gl/hr6mdb
24          extractor: class AvoidBacktickIssue {
25            static extract(content) {
26              return content.match(/[A-Za-z0-9_-]+/g) || [];
27            }
28          },
29          extensions: ['js'] // file extensions
30        }
31      ]
32    }),
33
34    // ...probably more plugins & things...
35  ]
36}