@zokki/astro-purgecss

This integration uses purgecss to remove unused css. This works for css-files and for style-tags in html-files.

Note

astro-purgecss only for statically generated build and pre-rendered routes.

Why

This integration was created to address two main challenges in Astro projects:

1. PurgeCSS often incorrectly removes CSS pseudo-selectors like :hover, :where, :is, :not, and :has. This integration includes proper safeguards to prevent these selectors from being purged.

2. Unlike other solutions, this integration can purge unused CSS not only from CSS files but also from style tags within HTML files, ensuring a more complete CSS optimization.

Installation

1. Install with npm.

   npm install @zokki/astro-purgecss
   

2. Import into the astro-config.

   import { purgecss } from '@zokki/astro-purgecss';
   
   export default defineConfig({
   	integrations: [purgecss()],
   });
   

Configuration

/**
 * Toggle logging of all purged files
 *
 * @default true
 */
logAllFiles?: boolean;
/**
 * Should purgecss purge styles in html-files
 *
 * @default true
 */
purgeInHtml?: boolean;
/**
 * A regex to extract css-vars from html
 *
 * @default /--[!\w\-%:+]+(?<!:)/g
 */
variableExtractor?: RegExp;
/**
 * Config for purgecss
 *
 * @default
 * {
 * 	defaultExtractor: content => content.match(/(--)?[!\w\-%:+]+(?<!:)/g) || [],
 * 	safelist: {
 * 		// purgecss falsly purges some css
 * 		standard: [
 * 			// don't purge astro default styles
 * 			/astro-/,
 * 			// https://github.com/FullHuman/purgecss/issues/1153
 * 			/:hover/,
 * 			// https://github.com/FullHuman/purgecss/issues/978
 * 			/:where/,
 * 			/:is/,
 * 			// https://github.com/FullHuman/purgecss/issues/1197
 * 			/:not/,
 * 			// https://github.com/FullHuman/purgecss/issues/1215
 * 			/:has/,
 * 		],
 * 	},
 * 	variables: true,
 * 	fontFace: true,
 * }
 */
purgecssConfig?: Omit<UserDefinedOptions, 'content' | 'css'>;

License

MIT © Tim-Niclas Oelschläger