CSS Bundle Shrinker

What this skill does

Runs PurgeCSS over a build's CSS output and source files, identifies unused classes, and proposes a safe purgecss.config.js — including an explicit safelist for class names constructed at runtime via string concatenation or template literals.

Inputs

• css_path: the built CSS file (e.g., dist/styles.css).
• source_globs: array of source file globs (['src/**/*.{js,ts,jsx,tsx,html}']).
• Optional safelist_extra: classes to never purge regardless.

Steps

1. Run npx purgecss --css <css_path> --content <source_globs> --output /tmp/purged/ and capture the size delta.
2. Diff the original and purged CSS to enumerate purged class names.
3. Run a string-construction scan over source_globs: detect \btn-${x}`, 'class-' + name, clsx(...), cx(...)` patterns. Extract literal prefixes as candidate safelist entries.
4. Run a JSX runtime-class scan: any className={\...${...}...`}` with non-trivial interpolation flags the surrounding component for safelisting.
5. Build the proposed purgecss.config.js:

   module.exports = {
     content: <source_globs>,
     safelist: { standard: [...explicit...], greedy: [/^prefix-/...] },
     defaultExtractor: content => content.match(/[A-Za-z0-9-_:/]+/g) || [],
   };
   

6. Add :root variables, keyframes referenced by safelisted classes, and Tailwind dark: / hover: variants explicitly to the safelist.
7. Write the config and the diff report.
8. Compute bytes saved before/after gzip: gzip -c <file> | wc -c.
9. Validate by re-running PurgeCSS with the new config; the safelist should preserve the dynamic-class candidates.

Output

Two files: purgecss.config.js (the proposed config) and css-shrink-report.md (table with: original size, purged size, gzipped sizes, list of safelisted patterns, count of removed classes). Stdout prints percent saved.

Verification

Build the app with the new config and visually compare against the previous build using a screenshot diff (playwright's expect(page).toHaveScreenshot()); pixel diff above 0.1% means a safelist gap. Re-run on a representative set of dynamic UI states (modals open, tabs switched). If gzipped size grows after purge (unlikely but possible with verbose safelist), revert.

Edge cases

• CSS-in-JS frameworks (styled-components): purging the static CSS is safe, but runtime CSS isn't covered; surface a note.
• Tailwind JIT: PurgeCSS is largely redundant; recommend the JIT mode setting instead.
• Atomic CSS (e.g., classes with colons like md:hover:bg-blue-500): use the defaultExtractor shown above; default extractor strips colons.
• Server-rendered HTML inside a CMS (classes coming from authored content): require safelist_extra to be populated, else risk visible breakage.