This comment can be in any script file inside src.

#### 3. Use Regex pattern to exclude many selectors

safelist option is available from purgecss

`js
purgeCSSOptions: {
safelist: [/^btn/], // Don't remove this selector
}
`

#### 4. Use purgecss ignore comment in css file

`css
/ purgecss ignore /
.my-selector {
color: 'white';
}
`

This comment will ignore the selector on the next line.

#### 5. Use purgecss ignore block comments in css file

`css
/ purgecss start ignore /
button {
color: 'white';
}
.yo {
color: 'blue';
}
/ purgecss end ignore /
`

This comment pair will ignore all css selectors between them.

#### 6. Ignore files and folder using the ignore options

`js
ignore: [
'ignoredFile.css',
'ignoredFolder/',
'sub/folder/ignore/',
'inFolder/file.css',
];
`

Note: always use forward slash / for folders, even on Windows.
Read about ignore option.

#### 7. Purge only specified files and skip everything else

`js
purgeOnly: ['/mainstyles.css', 'node_modules/bootstrap'];
`

Note: always use forward slash / for folders, even on Windows.
Good if you only need to purge some large css library and not touch anything else.
Read about purgeOnly option.

#### 8. For selector with dashes in them and using named imports

You _could_ write it like className={style['my-selector']} instead.

$3

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.
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.

If you do find/write a better extractor suited for Gatsby, please help me add it to the docs.

Important Notes

$3

By default, this plugin only runs when building the project (gatsby build).
It will print the amount of css removed.
To run it while using gatsby develop, use the develop: true option.

$3

The size reported by this plugin is the approximate size of the css content _before_ any optimizations have been performed.
The actual file size should be smaller.

$3

This plugin loads css files (or transformed output from css plugins) and searches for matching selectors in js, jsx, ts, tsx files in src/. 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/.

$3

Since html and body tags do not appear in src/ files, it is safelisted by default to not be removed.

$3

Sass/Less/Stylus(or any other loader) -> PostCSS -> PurgeCSS -> CSSLoader -> (CSSExtract/StyleLoader)
Note: Sass/Less/Stylus @imports are executed before this plugin, therefore, it won't see the @imported files as separate files.

Options

Options can be specified in your gatsby-config.js file like so:

`js
module.exports = {
plugins: [
{
resolve: 'gatsby-plugin-purgecss',
options: {
printRejected: true,
purgeCSSOptions: {
safelist: [],
},
},
},
],
};
`

Purgecss options can be specified under the purgeCSSOptions key.

> Read about all the purgecss options

$3

Print the list of removed selectors
printRejected: boolean

`js
printRejected: true;
`

It will print maximum of 100 removed selector per file to keep the output readable.
To view all the removed selector enable the printAll option.
default: false

$3

Enables printRejected to print all the rejected selectors.
(Output can get messy)
printAll: boolean

`js
printAll: true;
`

Needs printRejected option to be true.
default: false

$3

Only purge these files/folders.
ignore: Array

`js
purgeOnly: ['/main.css', 'bootstrap/', 'node_modules/font-awesome/'];
`

Note: always use forward slash / for folders, even on Windows.
Can be combined with the ignore option.
default: []

$3

Stop these files or folders from getting purged.
ignore: Array

`js
ignore: [
'/ignoredFile.css',
'ignoredFolder/',
'sub/folder/ignore/',
'inFolder/file.css',
];
`

Note: always use forward slash / for folders, even on Windows.
default: []

$3

Enable Tailwind support.
> 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.

tailwind: boolean

`js
tailwind: true;
`

Uses extractors needed for parsing tailwind class names.
Enable if you are using tailwindcss.
default: false

$3

Enable plugin while using gatsby develop.
develop: boolean

`js
develop: true;
`

This does not print the total css removed.
To see what is being removed, use it with the printRejected option.
default: false

$3

Enable debugging
debug: boolean

`js
debug: true;
`

It will write two files to disk.
gatsby-plugin-purgecss-debug-config.js with Gatsby's webpack config.
gatsby-plugin-purgecss-debug.js with the errors encountered.
default: false

$3

Print the total removed css stats.
printSummary: boolean

`js
printSummary: true;
`
default: true

$3

Stops from removing these selectors.
safelist: Array

`js
purgeCSSOptions: {
safelist: ['my-selector', 'footer'];
}
`
More options for safelist

Note: do NOT add . or # for classes and ids.
'html', 'body' are always safelisted.
Since v2.3.0 manually including 'html', 'body' is no longer required.
default: []

$3

Files to search for selectors.
content: Array

`js
purgeCSSOptions: {
content: [
path.join(process.cwd(), 'src/*/!(.d).{ts,js,jsx,tsx}'),
path.join(process.cwd(), 'anotherFolder/!(*.d).{ts,js,jsx,tsx}'),
];
}
`

default: [path.join(process.cwd(), 'src/*/!(.d).{ts,js,jsx,tsx}')]`

$3

Read about other purgecss options.

Versioning

gatsby-plugin-purgecss uses SemVer for versioning.

Acknowledgment

This project was made possible due to the incredible work done on the following projects:

- purgecss
- purgecss-loader
- gatsby

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

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.
Your contribution is greatly appreciated and will motivate me to continue to support developing my packages which you may have used.