Configuration

PurgeCSS has a list of options that allow you to customize its behavior. Customization can improve the performance and efficiency of PurgeCSS. You can create a configuration file with the following options.

Configuration file

The configuration file is a simple JavaScript file. By default, the JavaScript API will look for purgecss.config.js.

module.exports = {
    content: ['index.html'],
    css: ['style.css']
}

You can then use PurgeCSS with the file:

const purgecss = new Purgecss()
// or use the path to the file as the only parameter
const purgecss = new Purgecss('./purgecss.config.js')

Options

{
  content: Array<string | RawContent>,
  css: Array<string | RawContent>,
  extractors?: Array<ExtractorsObj>,
  whitelist?: Array<string>,
  whitelistPatterns?: Array<RegExp>,
  whitelistPatternsChildren?: Array<RegExp>,
  keyframes?: boolean,
  fontFace?: boolean,
  rejected?: boolean
}

  • content

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.

new Purgecss({
    content: ['index.html', '**/*.js', '**/*.html', '**/*.vue'],
    css: ['css/app.css']
})

PurgeCSS also works with raw content. To do this, you need to pass an object with the raw property instead of a filename. To work properly with custom extractors you need to pass the extension property along with the raw content.

new Purgecss({
    content: [
        {
            raw: '<html><body><div class="app"></div></body></html>',
            extension: 'html'
        },
        '**/*.js', '**/*.html', '**/*.vue'],
    css: [{
            raw: 'body { margin: 0 }'
        },
        'css/app.css']
})

  • extractors

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.

new Purgecss({
    content: ['index.html', '**/*.js', '**/*.html', '**/*.vue'],
    css: ['css/app.css'],
    extractors: [
        {
            extractor: class {
                static extract(content) {
                    return content.match(/a-Z/) || []
                }
            },
            extensions: ['html', 'blade']
        }
    ]
})

More information about extractors here.

  • whitelist

You can whitelist selectors to stop PurgeCSS from removing them from your CSS. This can be accomplished with the options whitelist and whitelistPatterns.

const purgecss = new Purgecss({
    content: [], // content
    css: [], // css
    whitelist: ['random', 'yep', 'button']
})

In the example, the selectors .random, #yep, button will be left in the final CSS.

  • whitelistPatterns

You can whitelist selectors based on a regular expression with whitelistPatterns.

const purgecss = new Purgecss({
    content: [], // content
    css: [], // css
    whitelistPatterns: [/red$/]
})

In the example, selectors ending with red such as .bg-red will be left in the final CSS.

  • whitelistPatternsChildren

You can whitelist selectors based on a regular expression with whitelistPatternsChildren. Contrary to whitelistPatterns, it will also whitelist children of the selectors.

const purgecss = new Purgecss({
    content: [], // content
    css: [], // css
    whitelistPatternsChildren: [/red$/]
})

In the example, selectors such as red p or .bg-red .child-of-bg will be left in the final CSS.

  • keyframes (default: 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.

new Purgecss({
    content: ['index.html', '**/*.js', '**/*.html', '**/*.vue'],
    css: ['css/app.css'],
    keyframes: true
})

  • fontFace (default: false)

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

new Purgecss({
    content: ['index.html', '**/*.js', '**/*.html', '**/*.vue'],
    css: ['css/app.css'],
    fontFace: true
})

  • rejected (default: false)

It can sometimes be more practical to scan through the removed list to see if there's anything obviously wrong. If you want to do it, use the rejected option.

new Purgecss({
    content: ['index.html', '**/*.js', '**/*.html', '**/*.vue'],
    css: ['css/app.css'],
    rejected: true
})
PreviousIntroductionNextCLI

Last updated