Skip to content

LSCWP Critical CSS: generating, applying, and troubleshooting

Use LSCWP to generate, inline, and maintain Critical CSS for above-the-fold rendering speed — including the cloud path, manual overrides, and broken layout fixes.

Critical CSS is the minimal set of styles required to render the above-the-fold portion of a page without waiting for the full stylesheet to download. Inlining it in the <head> eliminates render-blocking CSS requests and is one of the more reliable ways to improve Largest Contentful Paint scores. LSCWP can generate and apply Critical CSS automatically via the ls.quic.cloud service or from a locally-generated string, and this article covers both paths along with the debugging workflow when the result breaks the visible layout.

How to verify

Check whether Critical CSS is currently active and what it contains:

# Fetch the page and look for the inline critical block
curl -s https://example.com | grep -A 5 "critical"

# Check LSCWP option state
wp option get litespeed.conf.optm-css-async
wp option get litespeed.conf.optm-ccss-gen

From the database, inspect stored critical CSS for a URL:

wp db query "SELECT url, dateline FROM \`$(wp db prefix)\`litespeed_css LIMIT 10;"

After a generation run, check the cloud API response:

wp litespeed-ccss status

What’s happening

When LSCWP’s CSS Async and Generate CCSS options are both enabled, the plugin intercepts the page response, records the URL and a fingerprint of the stylesheet set, and dispatches a generation job to ls.quic.cloud. The cloud service loads the page in a headless browser, identifies the styles required to render the viewport, and returns a minified CSS string. LSCWP stores that string in the litespeed_css database table and inlines it in the <head> on subsequent requests while loading the full stylesheet asynchronously via <link rel="preload">.

The process has a cold-start period. On the first request to a URL after LSCWP is configured, the page renders without Critical CSS inlined (it is in generation queue). The result is available after one to several minutes depending on cloud queue depth. Until then, users see the page without the optimisation — there is no flash of unstyled content, but LCP is not yet improved.

For pages that cannot or should not use the cloud (air-gapped servers, staging environments, or pages with login walls that prevent headless access), LSCWP accepts a manually-supplied CSS string that is inlined in place of the cloud-generated one.

The procedure

Step 1 — Enable CSS Async and CCSS generation.

Go to LiteSpeed Cache → Page Optimization → CSS Settings:

  • CSS Async — On (this makes the full stylesheet load non-blocking)
  • Generate CCSS — On
  • CCSS Separate File — Off initially; enable later if you want the critical CSS served as a separate preloaded file rather than fully inlined

Save and flush. The domain must have a valid API key (General → Domain Key) for the cloud generation to work.

Step 2 — Trigger generation.

After saving, visit the key page types on the site — front page, a post, a category archive, a WooCommerce product page — to populate the generation queue. You can also trigger via WP-CLI:

wp litespeed-ccss generate https://example.com
wp litespeed-ccss generate https://example.com/shop/

Wait a few minutes, then check status:

wp litespeed-ccss status

Step 3 — Verify inline output.

Load the page source and confirm the <style> block is present in the <head>:

curl -s https://example.com | grep -c '<style'
# Should be at least 1
curl -s https://example.com | sed -n '/<style/,/<\/style>/p' | head -20

Step 4 — Handle layout issues.

If the page renders incorrectly with critical CSS applied (elements unstyled, layout collapsed, hero image missing):

  1. Identify the missing style using browser DevTools — disable JavaScript, then note which selectors are absent from the inline block.
  2. Either purge and re-generate (LiteSpeed Cache → CSS Async → Purge Critical CSS for this URL), or supply a manual override.

For manual override, go to LiteSpeed Cache → Page Optimization → CSS Settings → CCSS Custom and enter your hand-crafted CSS for the affected URL pattern. The manual string takes priority over the cloud-generated one.

Step 5 — Exclude pages that should not use async CSS.

Some admin or authentication pages should not have async CSS (the flash of layout shift on login forms, for example):

Go to CSS Async Excludes and add:

/wp-login.php
/wp-admin/
/my-account/

Step 6 — Maintain after theme or plugin updates.

A theme update changes the stylesheet fingerprint. LSCWP detects this and re-queues generation. You can also manually flush:

wp litespeed-ccss purge all

Then visit the key pages again to repopulate the queue.

Common pitfalls

FOUC (Flash of Unstyled Content) on first load. Critical CSS has not yet been generated for this URL. This is normal during the cold-start window. If it persists for more than ten minutes, check that the domain API key is valid and that ls.quic.cloud can reach the site.

Critical CSS generated but layout still broken. The headless browser captures styles from a viewport that differs from your testing viewport. In LSCWP settings, match the viewport width in CCSS Settings to your design’s primary breakpoint (typically 1440px for desktop).

CSS Async enabled but full stylesheet still blocks. A plugin or theme is enqueuing a stylesheet with a blocking attribute or via @import. Find these with browser DevTools → Performance tab → render-blocking resources. Exclude those files from async loading.

Generation queue stuck. The site is behind an IP allowlist or HTTP auth that blocks ls.quic.cloud’s headless crawler. Either add the cloud service IPs to the allowlist or supply Critical CSS manually.

Critical CSS too large. If the generated block is over 30 KB, the inlining overhead negates the benefit. Reduce scope by adding noisy selectors to the Async CSS Exceptions list or providing a tighter manual string.


Critical CSS generation is one of the cloud features that requires accurate domain configuration and clear headless access. Stack Harbor configures CCSS, validates generation, and handles manual overrides when cloud access is restricted, all as part of managed operations.