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.
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 parameterconst purgecss = new Purgecss('./purgecss.config.js')
{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: [], // contentcss: [], // csswhitelist: ['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: [], // contentcss: [], // csswhitelistPatterns: [/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: [], // contentcss: [], // csswhitelistPatternsChildren: [/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})