Kirby meets PurgeCSS

This is a walkthrough on how to set up and use PurgeCSS with a Command-line interface (CLI) or with a Graphical user interface (GUI). PurgeCSS is a tool to remove unused CSS and it can be part of your development workflow.

This is where PurgeCSS comes into play. PurgeCSS analyzes your content and your CSS files. Then it matches the selectors used in your files with the ones in your content files. It removes unused selectors from your CSS, resulting in smaller CSS files.

Setup for CLI

Before we start, you need to install Node.js for the build process on your client machine. The latest version, which also includes npm (Node package manager) can be downloaded from the official Node.js website. You can test the successful installation by opening a terminal window and typing the following two commands:

Install Node

node --version

npm --version

Install PurgeCSS

We use a Kirby Starterkit or Plainkit to get started and create a new /purge folder in the project's root so that our folder structure looks like this:

Node.js Configuration

Also in the project's root, we create a package.json file that controls the build process. This file contains only a (build) script.

{
  "name": "projectname",
  "scripts": {
    "build": "npx purgecss -css assets/css/css-framework.css --content site/**/*.php --output purge/"
  }
}

Explanation

Use build to generate a final minified CSS file

• --css assets/css/css-framework.css: input file with your framework's CSS
• --content 'site/**/*.php': folder to watch for CSS framework's classes
• --output purge/: output folder with purged CSS

If you want to customize your PurgeCSS installation, you can create an additional config file purgecss.config.js in the project root. This file will then be automatically processed at build time if it exists.

module.exports = {
  css: ['assets/css/css-framework.css'],
  content: ['site/**/*.php'],
  output: 'purge/'
}

Build

Now we have a fully functional basic setup and are ready to generate our purged CSS file. Make sure you are in the project root folder and start the build script as follows:

npm run build

Setup with GUI

Before we start, please make sure Prepros is installed on your local machine. You can download the free unlimited trial from the official Prepros.io website. Prepros compiles your files, transpiles your JavaScript and provides a graphical user interface like CodeKit for Mac or Scout (only SASS & SCSS).

Prepros Configuration

1. Open Project Settings
2. Navigate to CSS Tools
3. Select CSS or Sass
4. Scroll to Tasks
5. Type the following command:

purgecss --css {{input}} --content "{{rawRootDir}}/site/**/*.php" --output {{outputDir}} {{output}}

6. Click on Add Custom Command

The command scans all PHP files inside the /site folder for CSS classes and writes them to the output CSS file, e.g. CSS_FRAMEWORK.min.css.

Process

When you now change the CSS/SASS/SCSS file (that includes your CSS framework), Prepros will automatically perform the custom command afterward when enabled and purge your final CSS.

All that's left to do is to add a link to this file in your HTML head tag in your header snippet (or your template).

// for CLI method use
<?= css('purge/CSS_FRAMEWORK.css') ?>

// for GUI method use
<?= css('assets/css/CSS_FRAMEWORK.min.css') ?>