Before you go, check out these stories!

Hackernoon logoPurgeCSS 2.0 Introduction: Remove Unused CSS From Your Project by@Ffloriel

PurgeCSS 2.0 Introduction: Remove Unused CSS From Your Project

Author profile picture

@FflorielFloriel Fedry

When you are building a website, you might decide to use a CSS framework like TailwindCSS, Bootstrap, MaterializeCSS, Foundation, etc… But you will only use a small set of the framework, and a lot of unused CSS styles will be included.

One optimization would be to remove the CSS that is not used. You can inspect the unused bytes of CSS via Chrome developer tools. Trimming your CSS will make your website load faster because the browser will request less code, and less CSS will be parsed.

How does PurgeCSS work?

PurgeCSS works simplistically. First, we look at the content of our website; it will be everything except our styles. For a simple project, it could be HTML and javascript files. From this content, we want to get a list of selectors that could be used in our CSS. Looking at the image below, we can see where the selectors are.

Once we have the list, the primary process begins. We parse the CSS file using postCSS. Then, we walk through the Abstract Syntax Tree (AST). We take a look at each rules and analyse the selectors that compose them. If we notice a selector that is not present in the list, it means it is not used, and we remove the rule.

On the CSS file above, PurgeCSS iterates over the rules, starting with p.It see p in the list and so decide to not remove it. For text-transparent , it does not see in the list and the rule is removed.

The process is simple to understand. But one of the main challenge and
considerations is the diverse types of files that can be used to define
the structure of your web applications or websites. You need to be able to get the selectors from HTML files, but also templating languages such as pug, twig, blade, and potential selectors can be hidden in script files like Javascript and Typescript.

To make sure you are able to work with every type of file you want,
PurgeCSS has a concept of extractors. An extractor is just a function that takes the content of a file and returns the list of potential
selectors. You can then define smart functions that will parse the
files, get the class names, ids, tag names, and attributes. Or you can
do something simpler like the default extractor, using a regex to get every word on the page.

Changes in PurgeCSS 2.0

PurgeCSS 2.0 is the second major version bump. Some of the changes and improvements made required breaking changes. If you are using a plugin (Webpack, Nuxt.js, postCSS, …), you will probably not be affected by those changes as the plugin will be modified.


The previous version of PurgeCSS worked synchronously. You would typically instantiate PurgeCSS and execute the process.

import Purgecss from 'purgecss';

const purgecss = new Purgecss({
  // options

const purgecssResults = purgecss.purge();

The new version of PurgeCSS works asynchronously. Thanksfully, async/await is well supported in the LTS versions of NodeJS. If you are using PurgeCSS on multiple websites or pages in the same times, you will see a difference in time of execution.

import PurgeCSS from "purgecss";

const purgecssResults = await new PurgeCSS().purge({
    // options

Font Faces and Keyframes

In the previous version of PurgeCSS, it was possible to remove unused
font-faces and keyframes with two respective options. Due to the consequences, those features could bring if not working correctly, the options were set to false by default because of reports of issues. While the options are still deactivated by default, those issues are now fixed.

CSS Variables

If you used PurgeCSS with BootstrapCSS, you might have noticed a list of CSS variables that were still present in the CSS files despite the fact they were not used. CSS variables are quite useful and are now well supported. A new option is available to remove unused CSS variables.

Extractor is a function

Bad design choices for an API happens. That was the case for the extractor; they needed to be a class with a static method. It is now a simple function that takes the content as an argument and returns either a precise object containing classes, ids, attributes names and values, and tags; or an array of selectors. This allows PurgeCSS to make the distinction between .my-class-name and #my-class-name.

Monorepo and Typescript

The new version has been written in Typescript to provide better support
for types and improve the developer experience. The repo has been
reorganized to simplify the maintenance of the project. You can find most of the plugins in the PurgeCSS repository. It will make it easier to maintain the plugins and to ensure they are using the latest version of PurgeCSS.

Drop support of NodeJS < 8

NodeJS 8’s End of Life is December 31, 2019. It means it will no longer
receive updates. While PurgeCSS might work on NodeJS < 8, it will be
tested on NodeJS ≤ 8, including NodeJS 8, 10 and 12.

PurgeCSS on GitHub

PurgeCSS documentation

About the author
I’m Floriel, a software engineer at Full Human. You can follow me on GitHub and Twitter.

Previously published at


The Noonification banner

Subscribe to get your daily round-up of top tech stories!