postcss-purgecss

PostCSS Purgecss

PostCSS plugin for PurgeCSS.

Installation

npm i -D @fullhuman/postcss-purgecss postcss

Usage

const purgecss = require('@fullhuman/postcss-purgecss')
postcss([
  purgecss({
    content: ['./src/**/*.html']
  })
])

See PostCSS docs for examples for your environment.

Options

All of the options of purgecss are available to use with the plugins. You will find below the main options available. For the complete list, go to the purgecss documentation website.

content (required or use contentFunction instead)

Type: Array<string>

You can specify content that should be analyzed by Purgecss with an array of filenames or globs. The files can be HTML, Pug, Blade, etc.

contentFunction (as alternative to content)

Type: (sourceInputFile: string) => Array<string>

The function receives the current source input file. With this you may provide a specific array of globs for each input. E.g. for an angular application only scan the components template counterpart for every component scss file:

purgecss({
  contentFunction: (sourceInputFileName: string) => {
    if (/component\.scss$/.test(sourceInputFileName))
      return [sourceInputFileName.replace(/scss$/, 'html')]
    else
      return ['./src/**/*.html']
  },
})

extractors

Type: Array<Object>

Purgecss can be adapted to suit your needs. If you notice a lot of unused CSS is not being removed, you might want to use a custom extractor. More information about extractors here.

safelist

You can indicate which selectors are safe to leave in the final CSS. This can be accomplished with the option safelist.

Two forms are available for this option.

safelist: ['random', 'yep', 'button', /^nav-/]

In this form, safelist is an array that can take a string or a regex.

The complex form is:

safelist: {
    standard: ['random', 'yep', 'button', /^nav-/],
    deep: [],
    greedy: [],
    keyframes: [],
    variables: []
}

blocklist

Blocklist will block the CSS selectors from appearing in the final output CSS. The selectors will be removed even when they are seen as used by PurgeCSS.

blocklist: ['usedClass', /^nav-/]

Even if nav-links and usedClass are found by an extractor, they will be removed.

skippedContentGlobs

If you provide globs for the content parameter, you can use this option to exclude certain files or folders that would otherwise be scanned. Pass an array of globs matching items that should be excluded. (Note: this option has no effect if content is not globs.)

skippedContentGlobs: ['node_modules/**', 'components/**']

Here, PurgeCSS will not scan anything in the "node_modules" and "components" folders.

rejected

Type: boolean Default value: false

If true, purged selectors will be captured and rendered as PostCSS messages. Use with a PostCSS reporter plugin like postcss-reporter to print the purged selectors to the console as they are processed.

keyframes

Type: boolean Default value: false

If you are using a CSS animation library such as animate.css, you can remove unused keyframes by setting the keyframes option to true.

fontFace

Type: boolean Default value: false

If there are any unused @font-face rules in your css, you can remove them by setting the fontFace option to true.

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

Versioning

postcss-purgecss use SemVer for versioning.

License

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

Changelog

5.0.0 (2022-09-13)

Bug Fixes

• add safelist variables to postcss-purgecss #840 (c822058)
• gulp-purgecss: support skippedContentGlobs option #853 (b72de77)
• Purgecss webpack plugin/only filter fix (#933) (f8e4c2c)
• purgecss-webpack-plugin: add sourcemap support #409 (b3f73ed)
• purgecss-webpack-plugin: export as named export as well as default (#821) (a6a2c8e)
• wrong path import (4f3ddd0)

Features

• add source map support #526 (f2a9c5a)
• gulp-purgecss: add support for gulp-sourcemaps #257 (55c26d2)
• postcss-purgecss: load options from purgecss config (4de3bd8)
• purgecss-webpack-plugin: load config file automatically #767 (726faaa)

BREAKING CHANGES

• purgecss-webpack-plugin: drop webpack 4 support