Newborn Programming Monsters

    purgecss-whitelister

    2.4.0 • Public • Published
    
    /\ \  __/\ \/\ \      __/\ \__       /\_ \   __        /\ \__
    \ \ \/\ \ \ \ \ \___ /\_\ \ ,_\    __\//\ \ /\_\    ___\ \ ,_\ 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...
      ]
    }

    Keywords

    none

    Install

    npm i purgecss-whitelister

    DownloadsWeekly Downloads

    2,755

    Version

    2.4.0

    License

    MIT

    Unpacked Size

    8.04 kB

    Total Files

    3

    Last publish

    Collaborators

    • avatar