🚀 Astro Purgecss
Purgecss helps you remove unused CSS rules from your final astro bundle.
📦 Installation
Quick Install
the astro add
command-line tool automates the installation for you. Run one of the following commands in a new terminal window. (If you aren’t sure which package manager you’re using, run the first command.) Then, follow the prompts, and type “y” in the terminal (meaning “yes”) for each one.
# Using PNPM
pnpm astro add astro-purgecss
# Using NPM
npx astro add astro-purgecss
# Using Yarn
yarn astro add astro-purgecss
Manual Install
First, install the purgecss
& astro-purgecss
packages using your package manager. (If you aren’t sure which package manager you’re using, run the first command.)
Using PNPM
pnpm install purgecss astro-purgecss
Using NPM
npm install purgecss astro-purgecss
Using Yarn
yarn add purgecss astro-purgecss
Then, apply this integration to your astro.config.mjs
file using the integrations property:
import purgecss from 'astro-purgecss';
export default {
// ...
integrations: [purgecss()]
};
Note
To make sure this integration works properly, it's recommended to put
purgecss()
as the last element in theintegrations
array.
🥑 Usage
When you install this integration, things will be auto-wired for you. and all your generated css files should be purged from unused classes automagically.
📖 Configuration
PurgeCSS has a list of options that allow you to customize its behavior. And this Astro integration allow you to pass those options easily in your astro.config.mjs
file:
export default defineConfig({
integrations: [
purgecss({
fontFace: true,
keyframes: true,
safelist: ['random', 'yep', 'button', /^nav-/],
blocklist: ['usedClass', /^nav-/],
content: [
process.cwd() + '/src/**/*.{astro,vue}' // Watching astro and vue sources (for SSR, read the note below)
]
})
]
});
Note
If you are using Astro SSR in your project, you must add your astro and framework sources files into the
content
option (see in the example). Otherwise, as the package only look at the final build sent to the client, with SSR, some pages may not be included and may break your CSS.
Available Options
Here is a list of options, that are allowed to be passed in the config:
export type PurgeCSSOptions = {
fontFace?: boolean; // removes any unused @font-face if set to true
keyframes?: boolean; // removes unused keyframes by setting if set to true
rejected?: boolean; // scan through the removed list to see if there's anything wrong
rejectedCss?: boolean; // keeps the discarded CSS
variables?: boolean; // removes any unused CSS variables if set to true
safelist?: UserDefinedSafelist; // indicates which selectors are safe to leave in the final CSS
blocklist?: StringRegExpArray; // blocks the CSS selectors from appearing in the final output CSS
content?: Array<string | RawContent>;
};
To learn more about the available options, please refer to PurgeCSS official docs.
We have also setup an example repository available here: example-purgecss
Caveats
-
Some options are not allowed to be passed in your
astro.config.mjs
config file, to not interfere with the internals of this integration. -
If you are using inline styles, this plugin won't be able to purge those css rules, due to astro's way of handling scoped css rules.
-
If you are using
tailwind.css
, please read about purge limitations in this guide writing-purgeable-html
Changelog
Please see the Changelog for more information on what has changed recently.