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
})

PreviousIntroduction NextCLI

Last updated 6 years ago