Static Site Generators in Production

Eliminating Render-Blocking CSS on Static Sites

A static site can ship perfect HTML and a tiny hero image and still paint slowly, because a single external stylesheet in <head> blocks the first paint for an entire network round trip. The browser will not render anything — not the heading, not the hero — until that CSS has downloaded and parsed. This guide removes that block: inline the critical slice, load the rest non-blocking, and purge the rules you never use. It is the render-delay companion to Largest Contentful Paint Optimization for Static Sites, within the broader Performance Optimization & Core Web Vitals for SSGs work.

Prerequisites

  • A static site (Astro, Hugo, Eleventy, or Jekyll) that currently links one or more external stylesheets in the document head.
  • A build step you can extend with a CSS tool (critical/critters for inlining, PurgeCSS for pruning).
  • Lighthouse or lhci and a deployed URL — the render-delay portion of LCP shows up clearly in the Lighthouse trace.
Render-blocking CSS versus inlined critical CSS Two timelines. The first shows HTML arriving, then a blocking stylesheet round trip, then first paint. The second shows HTML with inlined critical CSS painting immediately while the full stylesheet loads non-blocking. Where first paint happens on the timeline Blocking HTML styles.css (blocks paint) FCP 2.1s Inlined HTML + critical CSS FCP 0.9s styles.css (non-blocking) Inlining the critical slice lets the first paint happen on the HTML response, not after a separate CSS round trip.
A blocking stylesheet pushes first paint behind a full round trip; inlined critical CSS paints on the initial HTML while the full file loads in the background.

The Recipe

The fix has four moving parts: decide what counts as critical, inline that slice while deferring the rest, generate the slice automatically at build time, and cut the stylesheet down with a purge pass. Do them in that order — purging first shrinks everything that follows.

Build pipeline that splits one stylesheet into an inlined slice and a deferred file The full stylesheet enters the build. PurgeCSS drops unused rules, then a critical extractor evaluates the first viewport and splits the result into two outputs: an inlined critical slice that paints with the HTML, and a deferred cacheable stylesheet that loads without blocking. Both ship in the built page. One stylesheet in, two outputs, generated every build Full stylesheet 78 KB · every rule PurgeCSS drop unused classes Critical extractor match first viewport Inlined critical CSS first-viewport slice · ~9 KB paints with the HTML Deferred styles.css cacheable, immutable loads non-blocking Purge first so it shrinks everything downstream; the extractor then splits what is left into an inlined slice and a deferred file.
The build purges unused rules, then a critical extractor splits the result into an inlined first-viewport slice and a deferred cacheable stylesheet — both regenerated on every build so they never drift from the current design.

1. Decide what actually belongs in the critical slice

"Critical" means only the rules needed to paint the first viewport at the widths your visitors use: the layout container, the header, the hero, base typography, and the above-the-fold spacing. Everything below the fold — footer, article body deep down the page, print styles, hover states on off-screen controls — is not critical and belongs in the deferred file. The line moves with viewport height, so a critical extractor evaluates the page at a target size (say 360×640 for mobile) and keeps the rules whose selectors match elements inside that box. Getting this boundary right is what keeps the inlined slice small; a bloated "critical" file is the most common way this optimization backfires.

2. Inline the critical CSS, defer the rest

Inline the critical rules in a <style> tag so they arrive inside the HTML response, and load the full stylesheet without blocking using the preload-swap pattern:

<head>
  <style>/* critical CSS for the first viewport: layout, hero, typography */</style>
  <link rel="preload" href="/styles.css" as="style"
        onload="this.onload=null;this.rel='stylesheet'" />
  <noscript><link rel="stylesheet" href="/styles.css" /></noscript>
</head>

The preload fetches the file at high priority without blocking rendering, and the onload handler flips it to a real stylesheet once it arrives. The <noscript> fallback keeps styles working when JavaScript is off. Keep the inlined slice under ~14 KB so it fits in the first round trip alongside the HTML — that is roughly the initial congestion window, and staying inside it means the first paint needs exactly one round trip and no more.

A JavaScript-free alternative is the print-media swap: <link rel="stylesheet" href="/styles.css" media="print" onload="this.media='all'">. The browser treats a print stylesheet as non-render-blocking for screen, then the handler promotes it. Either pattern works; the preload version fetches earlier, so prefer it unless you need the stylesheet to apply with scripting fully disabled.

3. Generate the critical slice in the build, not by hand

Hand-maintained critical CSS goes stale the moment the design changes — a new hero component ships, its rules are missing from the inline slice, and the first paint renders unstyled until the deferred file lands. Generate it during the build so it always matches the current page. critters (Astro integrations bundle a version) and the standalone critical package both work:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import compress from 'astro-compress';

export default defineConfig({
  integrations: [compress({ CSS: true })],
  build: { inlineStylesheets: 'auto' }, // Astro inlines small CSS automatically
});

Astro's inlineStylesheets: 'auto' inlines any stylesheet below a size threshold directly into the page and drops the blocking <link>, which covers most content pages without a separate tool. Set it to 'always' only if your total CSS is genuinely small on every route; on a large shared stylesheet, let a critical extractor split it instead so you inline the first-viewport slice rather than the whole file. Because generation runs per page, a template-heavy site ends up with a critical slice tailored to each route — the docs landing page inlines its hero rules, an article inlines its prose rules — with no manual bookkeeping.

4. Purge unused CSS

Most stylesheets ship rules no page renders — utility frameworks are the worst offenders, often shipping tens of kilobytes of classes a given page never touches. PurgeCSS scans your templates and content for the class names actually used and drops the rest, which both shrinks the deferred file and trims what the critical extractor has to consider:

// purgecss.config.js
module.exports = {
  content: ['./src/**/*.{astro,html,md,mdx}'],
  safelist: [/^is-/, /^has-/], // protect dynamically applied classes
};

Use a safelist for class names generated at runtime — toggled by scripting, injected by a component, or built from string concatenation — that the scanner cannot see verbatim in source, or purging will remove styles that are genuinely used. Tailwind runs its own content-aware purge through the same mechanism; point its content globs at every template and Markdown source, and treat any class you assemble dynamically as a safelist candidate. After a purge, always diff a few rendered pages against the pre-purge build before shipping.

5. Keep web fonts from re-introducing render delay

Eliminating the CSS block only to have a font request stall the first paint is a common own-goal on text-led pages, where the Largest Contentful Paint element is a heading. Put your @font-face declarations and a font-display: swap in the critical slice so text paints immediately in a fallback face and reflows when the web font loads. The deeper fix — self-hosting and preloading the font file — belongs to Font Loading Strategies for Static Sites; coordinate the two so the font is not the new bottleneck once CSS is out of the way.

6. Confirm the block is actually gone

Do not trust the config; verify against a trace. Lighthouse's "Eliminate render-blocking resources" audit should report the stylesheet as no longer blocking, and the FCP/LCP values should drop. In Chrome DevTools, the Coverage tab shows how much of the deferred file is unused (aim the purge at anything consistently over ~40%), and the Network waterfall should show first paint happening on the HTML response rather than after a separate CSS request. Serve the built stylesheet with a long immutable cache lifetime — see CDN Caching Rules for SSGs — so returning visitors skip the deferred fetch entirely.

Measured Impact

Measured on a documentation landing page, throttled mobile profile (4x CPU, ~1.6 Mbps), median of five Lighthouse runs. The LCP element here was a heading, so render delay dominated:

ChangeCSS bytes (blocking)FCPLCP
Single 78 KB blocking stylesheet78 KB2.1s2.4s
Inline critical + defer full file9 KB inlined0.9s1.7s
+ PurgeCSS on the full file9 KB inlined / 22 KB deferred0.9s1.6s

Inlining a 9 KB critical slice and deferring the 78 KB file moved First Contentful Paint from 2.1s to 0.9s and LCP from 2.4s to 1.7s — the whole 1.2s FCP gain is the round trip the browser no longer waits on before its first paint. Purging the full stylesheet from 78 KB to 22 KB shaved the deferred load and brought LCP to 1.6s. The Lighthouse "Eliminate render-blocking resources" audit went from flagging 0.6s of potential savings to clean, and because none of this ships JavaScript, Total Blocking Time was unchanged — the win is pure render-path, not main-thread. The gain is largest on slow connections and cold caches, exactly the first-visit conditions the score weights most.

Pitfalls & Rollback

  • Critical CSS too large: inlining the whole stylesheet defeats caching and bloats every HTML response. Keep it to the first viewport, under ~14 KB.
  • Stale hand-written critical CSS: it blocks paint with rules the page no longer needs. Always generate it in the build.
  • Over-aggressive purge: dropping classes applied at runtime breaks styling. Protect them with a safelist and visually diff a few pages after purging.
  • Forgetting the <noscript> fallback: without it, the deferred stylesheet never applies when JavaScript is disabled.
  • A flash of unstyled content: if the critical slice omits a rule the first viewport needs, that element paints unstyled and then snaps into place when the deferred file lands — a visible flash and, if it moves layout, a Cumulative Layout Shift hit. Widen the extractor's viewport target or add the missing selector to the critical set.
  • Rollback: revert to a single blocking <link rel="stylesheet"> and remove the inline <style> and the build integration. The change is purely in generated HTML and the build config, so a git revert plus redeploy is enough.
What belongs in the critical slice Two panels. Critical CSS covers layout for the first viewport, typography, the header and the hero. Deferred CSS covers everything below the fold, hover and focus states, print styles and component styles for pages that use them. What belongs in the critical slice Inline as critical first-viewport layout and grid typography scale and colours header and navigation hero and its spacing Defer safely everything below the fold hover, focus and active states print stylesheet component styles used on some pages Deferring a layout rule produces a visible jump when the stylesheet lands — a render-blocking fix that creates a layout shift.
The rule that keeps this safe: anything that changes an element's size or position belongs in the critical slice, even if it is below the fold.

Conclusion

Render-blocking CSS is invisible until you measure it, but it can cost half a second of blank screen on every page. Inline the critical slice, defer the full file, and purge what no page uses. On the example page these steps moved FCP from 2.1s to 0.9s and LCP from 2.4s to 1.6s without changing a line of content. Combine this with the hero work in Reducing LCP from Hero Images on Static Sites and the priority hints in Optimizing LCP on Astro with Priority Hints for the complete LCP picture.

FAQ

What is render-blocking CSS?

An external stylesheet in the head that the browser must download and parse before it paints anything. Until that round trip finishes, the page stays blank, which delays First Contentful Paint and, when the LCP element is text, Largest Contentful Paint as well.

How big should the inlined critical CSS be?

Keep it to the rules needed to render the first viewport, typically under 14 KB so it fits in the first network round trip after the HTML. Bigger than that and you are inlining styles the first paint does not need, which bloats every HTML response.

Will inlining CSS hurt caching?

Inlined critical CSS is re-sent with every HTML document, so it is not cached separately. That is an acceptable trade for a small critical slice because HTML is short-lived anyway, while the full stylesheet still loads as a cacheable file with a long immutable lifetime.

Does purging unused CSS change what users see?

It should not, if configured correctly. Purge tools scan your templates and content for the class names actually used and drop the rest. The risk is dynamically generated class names the scanner cannot see, which you protect with a safelist.

Why does my page flash unstyled after I inline critical CSS?

The critical slice is missing a rule the first viewport actually needs, so that element paints unstyled and then restyles when the deferred stylesheet arrives. Widen the extractor's viewport target or add the missing selector to the critical set, and check it does not shift layout, which would also cost you Cumulative Layout Shift.