https://github.com/mohatt/gatsby-plugin-postbuild
Gatsby plugin for optimizing generated static files.
https://github.com/mohatt/gatsby-plugin-postbuild
gatsby gatsby-plugin minify optimization purgecss tailwindcss
Last synced: about 1 year ago
JSON representation
Gatsby plugin for optimizing generated static files.
- Host: GitHub
- URL: https://github.com/mohatt/gatsby-plugin-postbuild
- Owner: mohatt
- License: mit
- Created: 2021-02-10T20:05:42.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2025-05-06T16:54:28.000Z (about 1 year ago)
- Last Synced: 2025-05-13T01:17:52.425Z (about 1 year ago)
- Topics: gatsby, gatsby-plugin, minify, optimization, purgecss, tailwindcss
- Language: TypeScript
- Homepage:
- Size: 695 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Gatsby Postbuild
[![][npm-img]][npm-url] [![][ci-img]][ci-url] [![][codecov-img]][codecov-url] [![][gatsby-img]][gatsby-url] [![][license-img]][license-url]
Provides an easy way to transform, modify or optimize static files generated by Gatsby using an extendable
event-based tasks API. A Postbuild task is a set of functions that hook into certain
events emitted by [file transformers](#file-transformers).
The plugin comes with these tasks out of the box:
- [Purgecss](https://github.com/mohatt/gatsby-plugin-postbuild/blob/master/src/tasks/purgecss)
Optimizes HTML/CSS files by removing unused CSS selectors.
- [HTTP Headers](https://github.com/mohatt/gatsby-plugin-postbuild/blob/master/src/tasks/http-headers)
Automatically generates headers configuration file for different hosting providers
- [Minify](https://github.com/mohatt/gatsby-plugin-postbuild/blob/master/src/tasks/minify)
Minifies HTML inline scripts and styles using [terser](https://github.com/terser/terser) and [cssnano](https://github.com/cssnano/cssnano).
---
- [Installation](#installation)
- [Usage](#usage)
- [Options](#options)
- [Define your own task](#define-your-own-task)
- [Processing options](#processing-options)
- [Ignoring files](#ignoring-files)
- [Reporting](#reporting)
- [Defaults](#defaults)
- [File transformers](#file-transformers)
- [Lifecycle events](#lifecycle-events)
- [License](#license)
## Installation
Install with [npm](https://www.npmjs.com/)
```sh
$ npm install gatsby-plugin-postbuild
```
or [yarn](https://yarnpkg.com/)
```sh
$ yarn add gatsby-plugin-postbuild
```
## Usage
All tasks that come bundled with the plugin are disabled by default so you will need to explicitly enable the ones you're going to use
```javascript
// in your `gatsby-config.js`
plugins: [
{
resolve: `gatsby-plugin-postbuild`,
options: {
purgecss: {
enabled: true
},
'http-headers': {
enabled: true
}
}
}
]
```
Every task has its own options that can be set as well. See [`tasks`](https://github.com/mohatt/gatsby-plugin-postbuild/blob/master/src/tasks) from more info
```javascript
plugins: [
{
resolve: `gatsby-plugin-postbuild`,
options: {
purgecss: {
enabled: true,
ignore: ['resume/index.html'],
allowSymbols: true
},
'http-headers': {
enabled: true,
provider: 'netlify',
headers: {
'[*]': {
'X-Frame-Options': 'DENY',
'X-XSS-Protection': '1; mode=block'
}
}
}
}
}
]
```
## Options
### Define your own task
You can define custum events using the `events` option and the plugin will import them as a Postbuild task.
Lets say you want to manipulate the contents of `svg` files under `/public`, you can define a simple event like this:
```javascript
options: {
events: {
svg: {
contents: ({ raw, file }) => {
// do something with the data
return raw
}
}
}
}
```
You can also use a `glob` pattern to match specific files
```javascript
options: {
events: {
'/icons/*.svg': {
contents: ({ raw, file }) => {
// do something with the data
return raw
}
}
}
}
```
The `contents` event we used above is emitted by the [generic file transformer](#generic-file-transformer) which is used for unkown file types. Other known file types will have different set of events that will allow transforming files in a more structured way.
In this example, we will define an event that is specific to `html` files. Lets say you would like to strip out all comments from html files
```javascript
options: {
events: {
html: {
node: ({ node, file }) => {
if (node.nodeName === '#comment') {
file.adaptor.detachNode(node)
}
}
}
}
}
```
Learn more about the [HTML file transformer](#html-file-transformer)
### Processing options
You can change how files are processed using the `processing` option
```javascript
options: {
processing: {
strategy: 'parallel',
concurrency: 20
}
}
```
Processing strategy accepts two values:
- **parallel:** files will be read, processed and written in one step all at the same time (better memory consumption)
- **sequential:** files will be processed in 3 steps with the last step being run in sequential order (consumes more memory but allows processing files based on data collected from all files)
Concurrency option sets the maximum number of files to process at once and can be set for both processing strategies.
You can also specifiy custom processing options for a specific file type
```javascript
options: {
extensions: {
html: {
strategy: 'sequential',
concurrency: 15
}
}
}
```
### Ignoring files
You can exclude specific files from being processed by the plugin using `ignore` option
```javascript
options: {
ignore: [
'index.html',
'icons/logo.svg'
]
}
```
You can also exclude files from being processed by a specific task
```javascript
options: {
purgecss: {
ignore: [
'index.html',
'resume/index.html'
]
}
}
```
### Reporting
By default, the plugin:
- generates a `postbuild.log.json` under `/public` after every build
- prints a summary report during build with a list of file changes
You can change this behaviour using `reporting` option
```javascript
options: {
reporting: {
log: true,
console: false
}
}
```
or enable/disable the reporting feature as a whole with a `boolean` value
```javascript
options: {
reporting: false
}
```
### Defaults
These are the default plugin options defined in [`src/options.ts`](https://github.com/mohatt/gatsby-plugin-postbuild/blob/master/src/options.ts).
```javascript
plugins: [
{
resolve: 'gatsby-plugin-postbuild',
options: {
enabled: true,
reporting: true,
ignore: [],
events: {},
processing: {
strategy: 'parallel',
concurrency: 10
},
extensions: {}
}
}
]
```
## File transformers
Postbuild uses file transformers to process files of different types, file transformers read the files, processes them and emitt certain events, tasks define functions that hook into those events to perform certain actions. Thats basically how the plugin works.
### Generic file transformer
Handles files with unknown extensions.
#### Events
`contents: ({ raw, options, file, event, filesystem, gatsby }) => string`
- Emitted when the file is about to be written
### HTML file transformer
Uses [Parse5](https://github.com/inikulin/parse5) to compile HTML files into AST then emits some events to be consumed by tasks.
#### Events
`parse: ({ html, options, file, event, filesystem, gatsby }) => string`
- Emitted before parsing the HTML string
`tree: ({ options, file, event, filesystem, gatsby }) => void`
- Emitted after HTML is compiled into AST
`node: ({ node, options, file, event, filesystem, gatsby }) => void`
- Emitted for every AST node
`serialize: ({ options, file, event, filesystem, gatsby }) => void`
- Emitted before serializing AST back to HTML string
`write: ({ html, options, file, event, filesystem, gatsby }) => string`
- Emitted when the file is about to be written
## Lifecycle events
These events are emitted at certain run time points.
#### Events
`on.postbuild: ({ options, event, filesystem, gatsby }) => void`
- Emitted before processing files to allow tasks to run setup code
`on.shutdown: ({ options, event, filesystem, gatsby }) => void`
- Emitted after processing files to allow tasks to run teardown code
`[extension].configure: ({ config, options, event, filesystem, gatsby }) => void`
- Emitted before processing files of a certain extension to allow tasks to read/write processing options for that extension.
## License
[MIT][license-url]
[npm-url]: https://www.npmjs.com/package/gatsby-plugin-postbuild
[npm-img]: https://img.shields.io/npm/v/gatsby-plugin-postbuild.svg?logo=npm
[ci-url]: https://github.com/mohatt/gatsby-plugin-postbuild/actions/workflows/main.yml
[ci-img]: https://img.shields.io/github/workflow/status/mohatt/gatsby-plugin-postbuild/CI/master?logo=github
[codecov-url]: https://codecov.io/github/mohatt/gatsby-plugin-postbuild
[codecov-img]: https://img.shields.io/codecov/c/github/mohatt/gatsby-plugin-postbuild.svg?logo=codecov&logoColor=white
[gatsby-url]: https://www.gatsbyjs.org/packages/gatsby-plugin-postbuild
[gatsby-img]: https://img.shields.io/badge/gatsby->=3.0-blueviolet.svg?logo=gatsby
[license-url]: https://github.com/mohatt/gatsby-plugin-postbuild/blob/master/LICENSE
[license-img]: https://img.shields.io/github/license/mohatt/gatsby-plugin-postbuild.svg?logo=open%20source%20initiative&logoColor=white