Gatsby Postbuild

Gatsby plugin for optimizing/minifying generated HTML/CSS files after build through removal of unused CSS rules.

Building a Gatsby site running TailwindCSS
Building a Gatsby site running TailwindCSS

How it works

The plugin works diffrently than other plugins/techniques that utilize PurgeCSS with PostCSS to acheive the same goal. The main diffrence is that the plugin only runs after Gatsby builds the site, then optimizes the generated HTML/CSS files.

Under the hood

The plugin uses Parse5 library to compile the generated html files into ASTs then:

  • Removes all <style> nodes and their CSS from the tree
  • Stores a temporary pure HTML string without CSS
  • Analyzes all HTML trees to create a map that links HTML files with CSS/JavaScript assets
  • Walks through the orginal tree and removes unused CSS rules by running PurgeCSS against the pure HTML files (+ any scripts included) according to the linked map created in the previous step, that includes:

    • Inline CSS rules defined under <style> tags
    • Local CSS files defines as <link> tags
  • Serializes the tree back to HTML
  • Writes optimized HTML/CSS files


Install with npm

$ npm install --save gatsby-plugin-postbuild

or yarn

$ yarn add gatsby-plugin-postbuild

Quick Start

Add the plugin to your gatsby-config.js and you’re done, the plugin works well without any options

plugins: [


If you’re using Tailwind in your site you need to set purgecss.allowSymbols to true like this:

plugins: [
    resolve: `gatsby-plugin-postbuild`,
    options: {
      purgecss: {
        allowSymbols: true



These are the default plugin options defined in src/options.ts.

plugins: [
    resolve: 'gatsby-plugin-postbuild',
    options: {
      enabled: true,
      report: true,
      reportConsole: true,
      ignoreFiles: {
        webpack: ['app', 'polyfill'],
        pages: [],
        css: [],
        js: []
      allowSymbols: false,
      purgecss: {
        rejected: true,
        fontFace: false,
        keyframes: false,
        variables: false


Type: Boolean Default: true

Whether to run postbuild or not.


Type: Boolean Default: true

Write a postbuild.log.json file in /public directory with all the changes made.


Type: Boolean Default: true

Print a summary report during build for every changed file.


Type: Array Default: ['app', 'polyfill']

Webpack chunck names to ignore while purging CSS. You can find these at /public/webpack.stats.json.

Note: This option will exclude all assetes under the given chunck names


Type: Array Default: []

Pages to exclude from optimiztion. This will also exclude all style assets defined in those page.


Type: Array Default: []

CSS files to exclude from optimiztion. Paths should be relative to /public directory.


Type: Array Default: []

Javascript files to ignore while purging CSS. Paths should be relative to /public directory.


Type: Boolean Default: false

Sets a custom PurgeCSS extractor that allows CSS selectors to contain symbols (e.g TailwindCSS).

PurgeCSS options

The following options are passed to PurgeCSS while optimizing CSS. See PurgeCSS Options for more info.


Type: Boolean Default: true

Write a *.rejected.log file in /public with the rejected selectors for every file.


Type: Function Default: PurgeCSS.defaultExtractor

A custom PurgeCSS extractor to be used instead of the default one.


Type: (Array|Object) Default: []

Selectors that are safe to leave in the final CSS.


Type: Array|Object Default: []

Selectors that are blocked from appearing in the final CSS.


Type: Boolean Default: false

Remove any unused @font-face rules in your css.


Type: Boolean Default: false

Remove any unused @keyframes rules in your css.


Type: Boolean Default: false

Remove any unused variables in your css.