purgecss-laminar-webpack-plugin

Webpack plugin to remove unused css for scala.js + laminar projects.

Derived from the purgecss-webpack-plugin.

Important

The way PurgeCSS works is simple - you give it a list of classes that are actually used (well, normally it extracts this list itself, from a static html, or by extracting "words" from any text file, like a .js file), and then it uses that list to clean up the CSS, removing everything it believes is unused.

Thus, in order this plugin not to break your app in production - you need to avoid building CSS class names with string interpolation or any other string manipulation functions. Every CSS class must be literally present in your code as a whole string (or a substing separated with whitespace, for example this is perfectly fine: div(cls := "class-1 class-2 class-3")).

So, this will get broken:

def component(color: String) = div(cls := s"my-component-$color")

As a workaround one might use the whitelisting (which is a built-in feature of PurgeCSS). See PurgeCSS docs for details on that.

Install

yarn add purgecss-laminar-webpack-plugin --dev

Usage

So far this plugin was tested to work with the extract-css-chunks-webpack-plugin plugin.

const ExtractCssChunks = require('extract-css-chunks-webpack-plugin');
const PurgeCSSLaminarPlugin = require('purgecss-laminar-webpack-plugin').default;

module.exports = {
  // ...
  plugins: [
    new ExtractCssChunks({
        // ...
    }),
    new PurgeCSSLaminarPlugin(),
  ]
  // ...
}

See scala-js-laminar-starter.g8 for a full configuration example.

Options

The options available in purgecss Configuration are also available in the webpack plugin with the exception of css, content, extractors and defaultExtractor.

These options from purgecss-webpack-plugin are not implemented:

• paths
• only

Othewise you can check out the purgecss-webpack-plugin documentation for more details about configuration.

Filtering strings

You can reduce the number of strings that are considered to be potential CSS class names using the filters (these are applied AFTER the strings have been selected and broken down into CSS-class-name-like tokens):

export interface StringFilters {
  exclude?: (RegExp | StringMatcher)[];
  include?: (RegExp | StringMatcher)[];
  onlyAllLowerCase?: boolean;
  skipAllUpperCase?: boolean;
  minLength?: number;
  maxLength?: number;
}

module.exports = {
  // ...
  plugins: [    
    new PurgeCSSLaminarPlugin({
      stringFilters: {
        minLength: 2,
        maxLength: 30,
        skipAllUpperCase: true, // filters out strings like 'NOT-A-CLASSNAME',
        onlyAllLowerCase: true, // filters out strings like 'Not-a-ClassName',
        exclude: [
          // a string will be excluded if ANY of these matches

          /_/ // filters out strings that contain `_`,
          
          (s) => s.startsWith('a') && s.endsWith('e') // filters out strings that start with an `a` and end with an `e`
        ],
        include: [
          // same as exclude, but a string will be excluded if NONE of these match
        ]
      },
    }),
  ]
  // ...
}

Debug

Setting { debug: true } in the plugin options will make it generate a number of files in the .purgecss-laminar-debug/ directory when parsing the .js files, in case you need to debug something:

module.exports = {
  // ...
  plugins: [    
    new PurgeCSSLaminarPlugin({
      debug: true
    }),
  ]
  // ...
}

License

This project is licensed under the MIT License - see the LICENSE file for details.