Community Plugin
View plugin on GitHub
See starters using this

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

Installation

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: [
  `gatsby-plugin-postbuild`,
]

TailwindCSS

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
      }
    },
  }
]

Options

Defaults

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
      }
    },
  }
]

enabled

Type: Boolean Default: true

Whether to run postbuild or not.

report

Type: Boolean Default: true

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

reportConsole

Type: Boolean Default: true

Print a summary report during build for every changed file.

ignoreFiles.webpack

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

ignoreFiles.pages

Type: Array Default: []

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

ignoreFiles.css

Type: Array Default: []

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

ignoreFiles.js

Type: Array Default: []

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

allowSymbols

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.

purgecss.rejected

Type: Boolean Default: true

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

purgecss.defaultExtractor

Type: Function Default: PurgeCSS.defaultExtractor

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

purgecss.safelist

Type: (Array|Object) Default: []

Selectors that are safe to leave in the final CSS.

purgecss.blocklist

Type: Array|Object Default: []

Selectors that are blocked from appearing in the final CSS.

purgecss.fontFace

Type: Boolean Default: false

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

purgecss.variables

Type: Boolean Default: false

Remove any unused @keyframes rules in your css.

purgecss.keyframes

Type: Boolean Default: false

Remove any unused variables in your css.

License

MIT