@roots/bud-purgecss

PurgeCSS support can be added by installing the @roots/bud-purgecss extension.

Styles are only purged when running in production mode.

Installation

npm

npm install @roots/bud-purgecss --save-dev

Yarn

yarn add @roots/bud-purgecss --dev

pnpm

pnpm add @roots/bud-purgecss --save-dev

Configuration

You can configure PurgeCSS using the API provided by bud.purge.

See the PurgeCSS documentation to learn how to configure PurgeCSS.

For every option detailed in the PurgeCSS docs there is a corresponding method in bud.purge.

PurgeCSS option	Configuration method
blocklist	bud.purge.setBlocklist
content	bud.purge.setContent
css	bud.purge.setCss
defaultExtractor	bud.purge.setDefaultExtractor
dynamicAttributes	bud.purge.setDynamicAttributes
extractors	bud.purge.setExtractors
fontFace	bud.purge.setFontFace
keyframes	bud.purge.setKeyframes
output	bud.purge.setOutput
rejected	bud.purge.setRejected
rejectedCss	bud.purge.setRejectedCss
sourceMap	bud.purge.setSourceMap
variables	bud.purge.setVariables
safelist	bud.purge.setSafelist
skippedContentGlobs	bud.purge.setSkippedContentGlobs
stdin	bud.purge.setStdin
stdout	bud.purge.setStdout
variables	bud.purge.setVariables

Some of the most common options are demonstrated below.

Set blocklist

TS

bud.config.ts

import type {Bud} from '@roots/bud'

export default async (bud: Bud) => {
  bud.purge.setBlocklist(['random', 'yep'])
}

JS

bud.config.js

/** @param {import('@roots/bud').Bud} bud */
export default async (bud) => {
  bud.purge.setBlocklist(['random', 'yep'])
}

YML

bud.config.yml

purge:
  setBlocklist:
    - 'random'
    - 'yep'

JSON

bud.config.json

{
  "purge": {
    "setBlocklist": ["random", ".example-2"]
  }
}

Set safelist

TS

bud.config.ts

import type {Bud} from '@roots/bud'

export default async (bud: Bud) => {
  bud.purge.setSafelist(['.example', '.example-2'])
}

JS

bud.config.js

/** @param {import('@roots/bud').Bud} bud */
export default async (bud) => {
  bud.purge.setSafelist(['.example', '.example-2'])
}

YML

bud.config.yml

purge:
  setSafelist:
    - '.example'
    - '.example-2'

JSON

bud.config.json

{
  "purge": {
    "setSafelist": ["random", "yep"]
  }
}

Set content

TS

bud.config.ts

import type {Bud} from '@roots/bud'

export default async (bud: Bud) => {
  bud.purge.setContent(['index.html', '**/*.js', '**/*.html', '**/*.vue'])
}

JS

bud.config.js

/** @param {import('@roots/bud').Bud} bud */
export default async (bud) => {
  bud.purge.setContent(['index.html', '**/*.js', '**/*.html', '**/*.vue'])
}

YML

bud.config.yml

purge:
  setContent:
    - 'index.html'
    - '**/*.js'
    - '**/*.html'
    - '**/*.vue'

JSON

bud.config.json

{
  "purge": {
    "setContent": ["index.html", "**/*.js", "**/*.html", "**/*.vue"]
  }
}

Set CSS

TS

bud.config.ts

import type {Bud} from '@roots/bud'

export default async (bud: Bud) => {
  bud.purge.setCss(['**/*.css'])
}

JS

bud.config.js

/** @param {import('@roots/bud').Bud} bud */
export default async (bud) => {
  bud.purge.setCss(['**/*.css'])
}

YML

bud.config.yml

purge:
  setCss:
    - '**/*.css'

JSON

bud.config.json

{
  "purge": {
    "setCss": ["**/*.css"]
  }
}

WordPress configuration

Install the purgecss-with-wordpress package to use the PurgeCSS managed safelist.

npm

npm install purgecss-with-wordpress --save-dev

Yarn

yarn add purgecss-with-wordpress --dev

pnpm

pnpm add purgecss-with-wordpress --save-dev

See the PurgeCSS guide for more informationon how to configure PurgeCSS for use in WordPress themes and plugins.

An example implementation is provided below:

Example

import purgecssWordPress from 'purgecss with wordpress'

bud.purge
  .setContent([`views/**/*.php`])
  .setCss([`assets/styles/**/*.css`])
  .setSafelist(purgecssWordPress.safelist)

Defaults

By default, this extension uses the following configuration:

bud.purge.setContent([
  bud.path(`@src`, `*.{html,js,jsx,php,pug,rb,ts,tsx,vue}`),
  bud.path(`@src`, `**`, `*.{html,js,jsx,php,pug,rb,ts,tsx,vue}`),
])