critical weekly downloads statistics

critical

Extract the critical-path (above-the-fold) CSS from your HTML, inline it, and load the rest asynchronously — so the browser can paint the first screen without waiting on a full stylesheet.

Critical removes render-blocking CSS from the critical path, which is one of the most direct levers on Largest Contentful Paint and first render. It works for static sites, MPAs, and single-page apps, and it's built to be driven by humans, build pipelines, and coding agents alike.

Contents

• How it works • Quick start • Two engines • CLI reference • API reference • Inlining behavior • Tuning the above-the-fold set • MCP server (agents) • Recipes • Design principles • Requirements • Alternatives

How it works

Given an HTML document and its stylesheets, Critical:

1. Determines what's critical. It figures out which CSS rules style the content that paints above the fold — either by matching rules against the delivered DOM (fast, no browser) or by rendering the page in a real viewport (accurate, handles SPAs). See Two engines. 2. Inlines it. The critical rules go into a as the first child of so it wins the cascade race against the deferred sheets. 2. Stops each from blocking the first paint, using the preload strategy:

The preload starts the download early; the stylesheet applies after the above-the-fold content (already styled by the inlined critical CSS) has painted. There is no inline event handler, so this works under a strict script-src Content Security Policy, and **no fallback is needed** — the stylesheet loads normally whether or not JavaScript runs.

Add data-critical-skip to a to leave it untouched. For a strict style-src CSP, pass inline: { nonce: "…" } to stamp the injected with your nonce.

Tuning the above-the-fold set

• [data-critical-fold] (static engine). By default the static engine inlines all _used_ CSS. Mark the container that holds your above-the-fold content with data-critical-fold and the static engine scopes matching to that subtree, producing a tighter critical set without a browser. • Viewports (render engine). Use width/height or dimensions to define exactly what "above the fold" means. Multiple dimensions union their results — useful for shipping one critical set that covers both mobile and desktop. • @font-face, @keyframes, custom properties are preserved when referenced; unused @keyframes and empty @media/@supports/@layer blocks are pruned.

MCP server (agents)

Critical ships a Model Context Protocol server so an agent can call it as a tool and receive the structured report back directly:

The tool takes src/html (plus optional css, engine, inline, width, height) and returns the critical CSS, the rewritten HTML, and the report as structured content. Requires the optional @modelcontextprotocol/sdk peer dependency.

Recipes

Optimize a static build directory (in CI):

Programmatically, writing both outputs:

An SPA where the shell is empty until JS runs:

Design principles

• Two engines, automatically routed. The fast path runs whenever the delivered DOM is the source of truth; the browser is used only when it's actually needed. • Platform-first, few dependencies. Three runtime dependencies — lightningcss (parse + minify + dead-code), linkedom (DOM), css-tree (rule walking). Everything else is a Node built-in (fetch, parseArgs, styleText, fs.glob). Heavy capabilities (playwright, the MCP SDK) are optional peers, imported lazily — you only pay for what you use. • Deterministic and explainable. Stable output bytes and a structured report that says what ran, why, and what it saved. • Safe by default. Nothing is written without an explicit flag; deferral adds no inline scripts, so the output works under a strict Content Security Policy.

Requirements

• Node.js ≥ 22.13 • The render engine additionally needs playwright and a browser: npm i -D playwright && npx playwright install chromium. The static engine needs neither.

Alternatives

Critical isn't the only way to inline critical CSS, and it isn't always the right one — a purely prerendered site that just wants its used CSS inlined may be better served by a lighter, browser-free tool. For a thorough, fair comparison of Critical, Beasties (formerly Critters), Penthouse, and native platform approaches — including where each one is the better choice and a reproducible benchmark — see COMPARISON.md.

Maintainers

This module is brought to you and maintained by the following people:

• Addy Osmani - Creator (Github) • Ben Zörb - Primary maintainer (Github)

License

Apache-2.0 © Addy Osmani

Description from the npm listing.