/\ \ __/\ \/\ \ __/\ \__ /\_ \ __ /\ \__
\ \ \/\ \ \ \ \ \___ /\_\ \ ,_\ __\//\ \ /\_\ ___\ \ ,_\ 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:
npm 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.
const { resolve } = require('path')
const whitelister = require('purgecss-whitelister')
whitelister('./relative/path/to/my/styles.css')
whitelister(['./styles1.css', './styles2.scss'])
whitelister('./3rd/party/library/*.less')
whitelister([
'./node_modules/lib1/*.css',
'./node_modules/lib2/*.scss',
'./node_modules/lib3/*.less'
])
whitelister('./node_modules/cool-library/styles/*.*')
Webpack Example
This is essentially what I'm using in my webpack.config.js
file:
const whitelister = require('purgecss-whitelister')
const PurgecssPlugin = require('purgecss-webpack-plugin')
const glob = require('glob-all')
const { resolve } = require('path')
const webpackConfig = {
plugins: [
new PurgecssPlugin({
keyframes: false,
styleExtensions: ['.css'],
paths: glob.sync([
resolve(resolve(), 'src/**/*.js'),
resolve(resolve(), 'src/index.ejs')
]),
whitelist: whitelister('node_modules/typer-js/typer.css');,
extractors: [
{
extractor: class AvoidBacktickIssue {
static extract(content) {
return content.match(/[A-Za-z0-9_-]+/g) || [];
}
},
extensions: ['js']
}
]
}),
]
}