Gatsby plugin for purgecss. Removes unused css/sass/less/stylus from files and modules. Supports Tailwindcss, Bootstrap, Bulma etc.
npm install gatsby-plugin-purgecss






Remove unused css from css/sass/less/stylus files and modules in your Gatsby project using purgecss. š. Supports tailwind, bootstrap, bulma etc.
ā ļø NOTE: This is NOT an install and forget type plugin. By default, it may remove required styles too.
Please read Help! Purgecss breaks my site šÆ to make sure gatsby-plugin-purgecss does not cause you issues and TLDR for the important bits
š Read the latest docs here. ⢠Changelog - includes migration to v6 guide ⢠Older v5 doc
When used in gatsby-starter-bootstrap
!demo
When used in gatsby-starter-bootstrap-cv (installed by default)
!demo
- .css , .module.css
- .scss, .sass, .module.scss, .module.sass (via gatsby-plugin-sass)
- .less, .module.less (via gatsby-plugin-less)
- .styl, .module.styl (via gatsby-plugin-stylus)
``sh`
npm i gatsby-plugin-purgecss
> Add the plugin AFTER other css/postcss plugins
`jsgatsby-plugin-stylus
// gatsby-config.js
module.exports = {
plugins: [
,gatsby-plugin-sass
,gatsby-plugin-less
,gatsby-plugin-postcss
,gatsby-plugin-purgecss
// Add after these plugins if used
{
resolve: ,gatsby develop
options: {
printRejected: true, // Print removed selectors and processed file names
// develop: true, // Enable while using `
// tailwind: true, // Enable tailwindcss support
// ignore: ['/ignored.css', 'prismjs/', 'docsearch.js/'], // Ignore files/folders
// purgeOnly : ['components/', '/main.css', 'bootstrap/'], // Purge only these files/folders
purgeCSSOptions: {
// https://purgecss.com/configuration.html#options
// safelist: ['safelist'], // Don't remove this selector
},
// More options defined here https://purgecss.com/configuration.html#options
},
},
],
};
Read about all the available options.
- Define options in gatsby-config.js, not purgecss.config.js.tailwind: true
- If using tailwindcss, use the option.printRejected: true
- Use option to print the removed selectors.my-selector
- Only files processed by Webpack will be purged.
- will not match mySelector.ignore: ['packagename/']
- Whitelist required selectors or ignore files/folder using the Whitelist Solutions guide.
- Ignore complete packages with [](#ignore).purgeOnly: ['fileOrPackage/']
- To only purge specific files/packages use [](#purgeOnly).js, jsx, ts, tsx
- Only files are scanned for selectors by default. If you want to add md or mdx use content: [path.join(process.cwd(), 'src/*/!(.d).{ts,js,jsx,tsx,md,mdx}')] or better, just whitelist the required selectors.
- Tailwind now can use purgecss directly too so you may want to use that. This plugin has the benefit of being able to define more options (ignore, purgeOnly, printRejected etc.) and can purge CSS modules.
- Use printRejected: true option which will print the filenames and the selectors which were removed.
- Identify which of the required selectors were removed.
- Whitelist the required selectors or completely ignore files using Whitelist Solutions guide.
- Look at the Issues section to understand why/how the purge was performed.
This section documents purgecss behavior in removing unused css. Most of the rules apply in any project and is not gatsby-plugin-purgecss specific.
#### Issue 1: CSS file not getting purged
For gatsby-plugin-purgecss to work on a css file it must be imported by a script file inside your src folder. This plugin depends on webpack to process css. If webpack does not use the css file then gatsby-plugin-purgecss cannot process it.
Also, make sure that you included the plugin after sass/less/stylus/postcss plugins.
#### Issue 2: Selectors with dashes in name gets removed when used with named imports
For eg:
style.css
`css`
.my-selector {
color: 'white';
}
index.js
`jsx`
// Named import
import style from './style.css';
...
ā
Here .my-selector will get removed since purgecss by default cannot match it with mySelector.
Read how to solve this issue in the "Whitelist Solutions" section.
_Note: Directly importing and using the selector name as is will work as intended_
` #### Issue 3: Styles getting purged even though the script file has selector names Make sure that the script file is in the #### Issue 4: Getting "Could not parse file, skipping. Your build will not break." > If you use postcss syntax based plugins then read this. Something is wrong. Good news is #### Issue 5: Using npm packages with components which import css files If you import a npm package which imports its own styles locally, then gatsby-plugin-purgecss will incorrectly remove all the css imported by the package. It's because by default the selectors are only matched with the files under 'src' folder. #### Issue 6: Works in #### Issue 7: Selectors in markdown (.md, .mdx) files are getting removed Markdown files are not scanned for selectors by default. Note: This may decrease the amount of styles removed because purgecss will consider every word in the markdown file to be a selector. You can use any of these techniques to stop purgecss from removing required styles #### 1. Whitelist the selector using the safelist option in gatsby-config.js #### 2. Use a JavaScript comment This comment can be in any script file inside #### 3. Use Regex pattern to exclude many selectors #### 4. Use purgecss ignore comment in css file This comment will ignore the selector on the next line. #### 5. Use purgecss ignore block comments in css file This comment pair will ignore all css selectors between them. #### 6. Ignore files and folder using the ignore options Note: always use forward slash #### 7. Purge only specified files and skip everything else Note: always use forward slash #### 8. For selector with dashes in them and using named imports You _could_ write it like Purgecss relies on extractors to get the list of selector used in a file. The default extractor considers every word of a file as a selector. If you do find/write a better extractor suited for Gatsby, please help me add it to the docs. By default, this plugin only runs when building the project ( The size reported by this plugin is the approximate size of the css content _before_ any optimizations have been performed. This plugin loads css files (or transformed output from css plugins) and searches for matching selectors in js, jsx, ts, tsx files in Since html and body tags do not appear in Sass/Less/Stylus(or any other loader) -> PostCSS -> PurgeCSS -> CSSLoader -> (CSSExtract/StyleLoader) Options can be specified in your Purgecss options can be specified under the > Read about all the purgecss options Print the list of removed selectors It will print maximum of 100 removed selector per file to keep the output readable. Enables Only purge these files/folders. Note: always use forward slash Stop these files or folders from getting purged. Note: always use forward slash Enable Tailwind support. Uses extractors needed for parsing tailwind class names. Enable plugin while using This does not print the total css removed. Enable debugging It will write two files to disk. Print the total removed css stats. Stops from removing these selectors. Note: do NOT add Files to search for selectors. default: Read about other purgecss options. gatsby-plugin-purgecss uses SemVer for versioning. This project was made possible due to the incredible work done on the following projects: - purgecss This project is licensed under the MIT License - see the LICENSE file for details. Hey š If my packages has helped you in any way, consider making a small donation to encourage me to keep contributing. Maintaining good software takes time and effort and for open source developers there is very less incentives to do so.jsx
import './style.css';my-selector} /> ā
`src folder. content
If you want to look for selectors in another folder, use the option.gatsby-plugin-purgecss should not cause any issue in such cases, files which could not be parsed will be skipped. If you want to diagnose the problem then use the debug option. Also, feel free to create a GitHub issue.ignore
To get around this, you could: optioncontent
2. Whitelist the required selectors as described in the next section.
3. Use the option and add the package's path.`
Eg:js`
content: [
path.join(process.cwd(), 'src/*/!(.d).{ts,js,jsx,tsx}'),
path.join(process.cwd(), 'node_modules/my-npm-package/folder-to-match/!(*.d).{ts,js,jsx,tsx}')
];develop, breaks in buildgatsby-plugin-purgecss by default does not run when using gatsby develop.content
Use the option. to add them.`js`
content: [path.join(process.cwd(), 'src/*/!(.d).{ts,js,jsx,tsx,md,mdx}')]`
If possible, just whitelist the required selectors instead of using this option.$3
js`
purgeCSSOptions: {
safelist: ['my-selector'], // Don't remove this selector
}`
PurgeCSS docs.
Read about safelist option.jsx`
// my-selectorsrc.safelist option is available from purgecss`js`
purgeCSSOptions: {
safelist: [/^btn/], // Don't remove this selector
}`css`
/ purgecss ignore /
.my-selector {
color: 'white';
}`css`
/ purgecss start ignore /
button {
color: 'white';
}
.yo {
color: 'blue';
}
/ purgecss end ignore /`js`
ignore: [
'ignoredFile.css',
'ignoredFolder/',
'sub/folder/ignore/',
'inFolder/file.css',
];/ for folders, even on Windows. `
Read about ignore option.js`
purgeOnly: ['/mainstyles.css', 'node_modules/bootstrap'];/ for folders, even on Windows. className={style['my-selector']}
Good if you only need to purge some large css library and not touch anything else.
Read about purgeOnly option. instead.gatsby build$3
You could use your own extractor (or get one made by other community members) to improve detection and further decrease your css file size.
Read more at Purgecss docs.Important Notes
$3
). gatsby develop
It will print the amount of css removed.
To run it while using , use the develop: true option.src/$3
The actual file size should be smaller.$3
. It does not know which css file belongs to which source file. Therefore, for eg., if there is a class .module in some css file, it will not be removed if it used in _any_ script file under src/.src/$3
files, it is safelisted by default to not be removed. @import$3
Note: Sass/Less/Stylus s are executed before this plugin, therefore, it won't see the @imported files as separate files.gatsby-config.jsOptions
file like so:`js`
module.exports = {
plugins: [
{
resolve: 'gatsby-plugin-purgecss',
options: {
printRejected: true,
purgeCSSOptions: {
safelist: [],
},
},
},
],
};purgeCSSOptions key.printRejected: boolean$3
`js`
printRejected: true;printAll
To view all the removed selector enable the option. false
default: printRejected$3
to print all the rejected selectors. printAll: boolean
(Output can get messy) `js`
printAll: true;printRejected option to be true. false
default: ignore: Array$3
`js`
purgeOnly: ['/main.css', 'bootstrap/', 'node_modules/font-awesome/'];/ for folders, even on Windows. ignore
Can be combined with the option. []
default: ignore: Array$3
`js`
ignore: [
'/ignoredFile.css',
'ignoredFolder/',
'sub/folder/ignore/',
'inFolder/file.css',
];/ for folders, even on Windows. []
default: tailwind: boolean$3
> Tailwind now can use purgecss directly too so you may want to use that. This plugin has the benefit of being able to define more options (ignore, purgeOnly, printRejected etc.) and can purge CSS modules.`js`
tailwind: true;false
Enable if you are using tailwindcss.
default: gatsby develop$3
. develop: boolean`js`
develop: true;false
To see what is being removed, use it with the printRejected option.
default: debug: boolean$3
`js`
debug: true;gatsby-plugin-purgecss-debug-config.js with Gatsby's webpack config. gatsby-plugin-purgecss-debug.js with the errors encountered. false
default: printSummary: boolean$3
`js`
printSummary: true;true
default: safelist: Array$3
`js`
purgeCSSOptions: {
safelist: ['my-selector', 'footer'];
}.
More options for safelist or # for classes and ids. 'html', 'body' are always safelisted. []
Since v2.3.0 manually including 'html', 'body' is no longer required.
default: content: Array$3
`js`
purgeCSSOptions: {
content: [
path.join(process.cwd(), 'src/*/!(.d).{ts,js,jsx,tsx}'),
path.join(process.cwd(), 'anotherFolder/!(*.d).{ts,js,jsx,tsx}'),
];
}[path.join(process.cwd(), 'src/*/!(.d).{ts,js,jsx,tsx}')]`$3
Versioning
Acknowledgment
- purgecss-loader
- gatsbyLicense
Support
Your contribution is greatly appreciated and will motivate me to continue to support developing my packages which you may have used.