Critical CSS and used CSS are independent, opt-in pipelines. Critical CSS prepares above-the-fold styles for a template; used CSS builds a page-specific stylesheet from selectors observed in the rendered URL. Start with one pipeline and test builder and dynamic states.
Critical CSS
When criticalCSS is enabled, the plugin generates a bounded, per-template critical stylesheet and serves it through the current template-enhancement/output-buffer path. It keeps a full-stylesheet fallback and respects strict CSP, size, retry, and commerce-exclusion settings. Generation status and failures are visible in the dashboard rather than silently treated as a successful render.
Used CSS
When removeUnusedCSS is enabled, the plugin parses the rendered URL and queued styles, preserves a built-in and user safelist, and writes a page-specific result with freshness checks. Dynamic state classes, builder output, and JavaScript-created markup belong in the safelist. A page purge removes the derived result so the next safe render can rebuild it.
Safe rollout
- Enable the feature on staging.
- Use Preview/Dry Run and inspect the generated selector list.
- Promote only after the health check passes.
- Keep the last-good artifact available for rollback.
- Re-test after a builder update, theme switch, or major template change.
Settings
| Key | Default | Purpose |
|---|---|---|
criticalCSS | false | Generate template critical CSS. |
removeUnusedCSS | false | Build per-URL used CSS. |
excludeUnusedCSS, ccssSafelistExtra | \'\' | Keep project-specific selectors. |
usedCSSDeliveryMode | file | Choose the safe file delivery mode. |
ccssMaxRetries, ccssGenTimeout | 5, 25 | Bound generation retries and timeout. |
When styles disappear
Add the dynamic selector to the relevant safelist, regenerate the affected URL, and inspect the health result. If the page still breaks, disable only the failing pipeline and clear its derived cache. A full-site deletion is a last resort, not the first diagnostic.