Skip to content
A utility for creating whitelists of CSS selectors for use with Purgecss.
Branch: master
Clone or download
Latest commit 623f15c Mar 31, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.gitignore Ignoring local test folder. May 29, 2018
README.md
index.js Updated dependencies. Code cleanup. Mar 30, 2019
package-lock.json 2.4.0 Mar 30, 2019
package.json 2.4.0 Mar 30, 2019

README.md


/\ \  __/\ \/\ \      __/\ \__       /\_ \   __        /\ \__
\ \ \/\ \ \ \ \ \___ /\_\ \ ,_\    __\//\ \ /\_\    ___\ \ ,_\ 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')

// Example 1 - simple string
whitelister('./relative/path/to/my/styles.css')

// Example 2 - array of strings
whitelister(['./styles1.css', './styles2.scss'])

// Example 3 - globby strings
whitelister('./3rd/party/library/*.less')

// Example 4 - array of globby strings
whitelister([
  './node_modules/lib1/*.css',
  './node_modules/lib2/*.scss',
  './node_modules/lib3/*.less'
])

// Example 5 - ALL THE THINGS
//
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 = {

  // ...a whole buncha stuffs up here...

  plugins: [
    new PurgecssPlugin({
      keyframes: false, // https://goo.gl/bACbDW
      styleExtensions: ['.css'],
      paths: glob.sync([
        resolve(resolve(), 'src/**/*.js'),
        resolve(resolve(), 'src/index.ejs')
      ]),

      // `whitelist` needed to ensure Typer classes stay in the bundle.
      whitelist: whitelister('node_modules/typer-js/typer.css');,
      extractors: [
        {
          // https://goo.gl/hr6mdb
          extractor: class AvoidBacktickIssue {
            static extract(content) {
              return content.match(/[A-Za-z0-9_-]+/g) || [];
            }
          },
          extensions: ['js'] // file extensions
        }
      ]
    }),

    // ...probably more plugins & things...
  ]
}
You can’t perform that action at this time.