# 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. ```sh npm install --save-dev critical ``` --- ## Contents - [How it works](#how-it-works) - [Quick start](#quick-start) - [Two engines](#two-engines) - [CLI reference](#cli-reference) - [API reference](#api-reference) - [Inlining behavior](#inlining-behavior) - [Tuning the above-the-fold set](#tuning-the-above-the-fold-set) - [MCP server (agents)](#mcp-server-agents) - [Recipes](#recipes) - [Design principles](#design-principles) - [Requirements](#requirements) - [Alternatives](#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](#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: ```html ``` 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 `

` 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](https://modelcontextprotocol.io) server so an agent can call it as a tool and receive the structured report back directly: ```sh node src/mcp.js # stdio MCP server exposing `optimize_critical_css` ``` ```js import { createServer } from "critical/mcp"; ``` 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):** ```sh critical ./dist --inline --write ``` **Programmatically, writing both outputs:** ```js import { writeFile } from "node:fs/promises"; import { critical } from "critical"; const { html, css } = await critical({ src: "dist/index.html", inline: true }); await writeFile("dist/index.html", html); await writeFile("dist/critical.css", css); ``` **An SPA where the shell is empty until JS runs:** ```js await critical({ src: "dist/index.html", engine: "render", inline: true }); // auto-routing would also pick "render" here; pinning it just skips the sniff. ``` ## 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](./COMPARISON.md). ## Maintainers This module is brought to you and maintained by the following people: - Addy Osmani - Creator ([Github](https://github.com/addyosmani)) - Ben Zörb - Primary maintainer ([Github](https://github.com/bezoerb)) ## License [Apache-2.0](license) © Addy Osmani