Overview

What it does for you

Frontend Optimizer can generate and inline above-the-fold CSS so public pages render their first visible content more quickly. It generates this Critical CSS automatically when a render profile does not already have it; there is no day-to-day cache-clearing action in the admin.

Configure global Critical CSS

Open the package’s Critical CSS settings from the extension settings surface. The global settings let a technical site administrator:

• enable or disable Critical CSS and its automatic generation;
• choose whether coverage is shared site-wide, by layout, or by page URL;
• set the maximum inlined CSS size and the viewports used for extraction; and
• adjust the fold calculation and Playwright wait/timeout settings used while generation samples pages.

The default page-URL scope is the safest choice for sites whose pages have different visual structures. Treat the extraction controls as technical configuration and involve a developer before changing them.

Before enabling automatic generation

Apply the package’s database and settings migrations, then confirm Diagnostics passes for the optimizer renderer, writable local manifest/CSS storage, Node and generator readiness, and the queue connection. Automatic generation requires a database, redis, sqs or beanstalkd queue driver and a running worker. The worker must also have the configured Node binary, the package’s Playwright dependency, and a Chromium browser available; otherwise jobs fail and pages remain on their normal stylesheet output.

Generation only opens enabled, registered site domains. Production blocks private or reserved network targets by default. If a deployment uses an internal origin, configure the documented private-target controls deliberately and keep them limited to that trusted environment.

Fine-tune a site, layout, or page

The Critical CSS tab also appears when editing a site, layout, or page. Use its Profile scope setting to override the broader setting only where necessary. A page additionally offers these controls:

• Use as canonical coverage page to prefer that published page when sampling its layout and page type;
• Always include this page when it needs site-wide coverage despite sharing a render shape; and
• Disable above-the-fold CSS to always deliver the full blocking stylesheet for that page.

Leave the scope blank to inherit the next broader setting. The tab shows whether a scope is explicit or inherited.

Generation, fallback, and recovery

The first public request for a new render profile stores its coverage and queues generation; it does not wait for Playwright. Until a valid artifact exists, or whenever Critical CSS is disabled, missing, oversized, or failed, the page keeps the full eligible stylesheet as blocking CSS. A generator failure is recorded against the profile and a later public visit can queue another attempt.

For a controlled deployment or recovery, a developer can run capell:frontend-optimizer:generate-critical-css for selected artifact IDs or hashes, or use --all. Add --verify to check existing artifacts without generating them; the command exits unsuccessfully when an artifact is missing, invalid, has no render profile, or exceeds the inline-size limit. Successful generation invalidates dependent frontend cache entries so a cached fallback response can be rebuilt with the generated CSS.

Keep the scheduler running. The daily capell:frontend-optimizer:prune-profiles task removes render profiles not updated for 30 days, their manifests, and orphaned generated CSS. Use its --dry-run, --days, and --limit options before a manual retention run when you need to inspect the impact.

Good to know

• Generated artifacts are refreshed automatically as needed; there is no manual “clear optimised files” control.
• Changes to the relevant page, layout, site, theme, asset graph, coverage, or extraction settings create a new artifact identity. The old artifact is retained until pruning rather than being overwritten in place.
• Turn Critical CSS off for a page only when you have verified that its generated output is unsuitable. The full stylesheet remains the fallback.
• This package optimises delivery; it does not replace the normal cache controls available elsewhere in Capell.

---

For how to use Frontend Optimizer, see the admin guide. For developers: see the README.