critical Documentation

1. Project Overview & Quickstart (addyosmani/critical) Copy Chapter

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.

npm install --save-dev critical

Contents Copy Chapter

• 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 Copy Chapter

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 <style> at the top of <head> so first paint
   needs only the HTML.
3. Defers the rest. Each <link rel="stylesheet"> is replaced in the head by a
   <link rel="preload"> and moved to the end of the body, so it no longer blocks first paint.
   No inline scripts are added, so it works under a strict Content Security Policy.

The output is deterministic: the same input produces byte-identical output, so it's safe to run
in CI and diff in version control.

Quick start Copy Chapter

CLI Copy Section

# Optimize a build directory in place (inlines critical CSS, defers the rest)
critical ./dist --inline --write

# See what it would do and why, without writing anything
critical ./dist --explain

# A single file to stdout
critical index.html --inline > index.critical.html

API Copy Section

import { critical } from "critical";

const { html, css, report } = await critical({
  src: "dist/index.html",
  inline: true,
});

// `html`   — the document with critical CSS inlined and stylesheets deferred
// `css`    — the critical CSS on its own (minified)
// `report` — structured diagnostics (engine used, bytes, rules, warnings, timing)

critical() never writes to disk on its own — it returns the result. Use the CLI's --write
/ --out, or write result.html / result.css yourself.

Two engines Copy Chapter

Critical picks the right strategy for each document automatically (engine: "auto", the
default), and tells you which it used and why.

Automatic routing. When engine is "auto", Critical inspects the delivered HTML. If the
document already contains rendered content, the static engine is correct and runs in
milliseconds. If the document is an empty application shell (e.g. `` with
no markup yet), there's nothing to match against statically, so Critical escalates to the render
engine and measures the page the way a browser actually paints it.

You can always pin the engine explicitly with engine: "static" or engine: "render".

The render engine uses Playwright, declared as an optional peer
dependency. It's imported lazily, so the static path — and the default install — never pull in
a browser. To use the render engine: npm i -D playwright && npx playwright install chromium.

CLI reference Copy Chapter

critical  [options]

  input        a directory (all *.html are processed), an .html file, or stdin

Examples Copy Section

critical ./dist --inline --write              # whole build dir, in place
critical index.html --explain                 # routing decision + size stats
critical app.html -e render -i > out.html     # force a real-browser pass for an SPA
critical page.html --dimensions 390x844,1300x900 -i   # union of mobile + desktop folds
cat page.html | critical --inline             # stdin -> stdout
critical ./dist --json                        # machine-readable report for CI/agents

API reference Copy Chapter

import { critical } from "critical";

`critical(options) → Promise<{ html, css, report }>` Copy Section

The inline object accepts:

The result Copy Section

const { html, css, report } = await critical({ src: "dist/index.html", inline: true });

• html — the document. Identical to the input unless inline is set.
• css — the critical CSS, minified (unless minify: false).
• report — structured diagnostics:

{
  "engine": "static", // engine that actually ran
  "reason": "rendered document (…) — matching used CSS without a browser",
  "requestedEngine": "auto",
  "rules": { "kept": 10, "total": 15 },
  "bytes": { "stylesheets": 1107, "critical": 544, "savedBlocking": 1107 },
  "stylesheetsDiscovered": ["/styles.css"],
  "stylesheetsDeferred": ["/styles.css"], // present when inlined
  "warnings": ["…"],
  "durationMs": 13,
  "deterministic": true,
}

report is designed to be read by a program: it explains the decision, quantifies the win
(savedBlocking = render-blocking bytes removed from the critical path), and surfaces any
caveats as warnings.

Inlining behavior Copy Chapter

With inline: true, Critical:

1. Inserts <style data-critical>…</style> as the first child of <head> so it wins the
   cascade race against the deferred sheets.

2. Stops each <link rel="stylesheet"> from blocking the first paint, using the preload strategy:

   html Copy

   <link rel="preload" as="style" href="/styles.css" />
   
   
   <link rel="stylesheet" href="/styles.css" />

   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 <noscript>
   fallback is needed — the stylesheet loads normally whether or not JavaScript runs.

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

Tuning the above-the-fold set Copy Chapter

• [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) Copy Chapter

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

node src/mcp.js     # stdio MCP server exposing `optimize_critical_css`

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 Copy Chapter

Optimize a static build directory (in CI):

critical ./dist --inline --write

Programmatically, writing both outputs:

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:

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 Copy Chapter

• 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 Copy Chapter

• 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 Copy Chapter

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.

License Copy Chapter

Apache-2.0 © Addy Osmani

2. Official Technical Reference & Guides (addyosmani/docs) Copy Chapter

File: README.md Copy Chapter

Polymer docs are mostly in Markdown with some HTML. Jekyll is used to generate the static HTML for the site. The output is generated into a folder called _site and served from Google App Engine.

Prereqs and installation requirements Copy Chapter

We use Jekyll 1.4.2+ and Grunt to generate the documentation. You'll need to install the requirements before working on the docs (these instructions assume NPM is already installed):

sudo gem install jekyll
sudo gem install kramdown
sudo npm install grunt-cli
npm install

You'll also need the App Engine SDK to run the dev_appserver and preview the docs locally. Download the SDK.

Check out the documentation Copy Section

Checkout this repo:

git clone https://github.com/Polymer/docs.git --recursive

Create a directory polymer-all/projects and run the pull-all-projects.sh script in that directory:

cd docs/polymer-all
mkdir projects; cd projects
../tools/bin/pull-all-projects.sh

This populates projects with a bunch of repositories. You'll periodically need to re-run pull-all-projects.sh whenever the site is released.

Next, create a components folder in the top level docs directory and run pull-all-polymer.sh and pull-all-elements.sh in it:

cd ../..
mkdir components; cd components
../polymer-all/tools/bin/pull-all-polymer.sh
../polymer-all/tools/bin/pull-all-elements.sh

Note: these scripts can take some time to download.

You should now be able to build the docs successfully. Run this in the main folder:

grunt docs

Making edits and previewing changes Copy Chapter

This repo (Polymer/docs) is where the documentation source files live. To make a change:

1. First, up the App Engine dev server in this folder (dev_appserver.py .) to preview the docs.
2. Make your edits.
3. To build the docs, run grunt in base of the docs diretory you checked out. This starts up jekyll and watches for changes as you make edits. Be sure to run npm install in your docs directory if it's a new checkout. It can take some time for the docs to fully regenerate and be copied to the output folder...keep refreshing!

Jekyll generates the static site in a folder named _site. Note: If you're not running jekyll to rebuild the site, you won't see your changes in the dev server.

Once your changes look good, git commit them and push.

Building and pushing the docs Copy Chapter

Note: only project owners can publish the documentation.

If you have things checked out correctly in components and polymer-all, you should be able to generate the prodcution documentation using:

grunt docs

It's a good idea to do this before pushing the docs, as it runs a number of grunt tasks. Verify things went well.

Last step is to push the docs to App Engine. In your Polymer/docs directory, run:

./scripts/deploy_site.sh

This script builds the site, api docs, runs Vulcanizer over the imports, and deploys to App Engine.

Polymer release Copy Chapter

When we push a new version of Polymer, the site should be updated to use it. In addition,
the element reference and other projects will need updating.

First, update the submodules in /docs:

git submodule foreach git pull origin master
git submodule update

Update the projects:

cd polymer-all/projects
../tools/bin/pull-all-projects.sh

Then, update the elements and polyfills:

cd components
../polymer-all/tools/bin/pull-all-polymer.sh
../polymer-all/tools/bin/pull-all-elements.sh

Once these are updated, you need to update some versions for the docs:

• Increment the version in app.yaml;
• Update the Polymer release version in _config.yml.
• Add a link point link to the release notes in changelog.md.

Build the docs:

grunt docs

At this point, run the dev server and preview things locally to make sure nothing is terribly
broken after Polymer and the elements have been updated.

Lastly, run the deploy script:

./scripts/deploy_site.sh

Last thing is to switch the app version in the App Engine admin console. To make the docs live, hit up https://appengine.google.com/deployment?&app_id=s~polymer-project and select the version you just deployed.

File: doc_themes/footstrap/README.md Copy Chapter

yuidoc-bootstrap-theme

A revamped yuidoc theme with bootstrap

File: doc_themes/bootstrap/README.md Copy Chapter

yuidoc-bootstrap-theme

A revamped yuidoc theme with bootstrap

File: docs/polymer/databinding.md Copy Chapter

layout: default title: Data-binding Copy Chapter

Introduction Copy Chapter

{{site.project_title}} supports two-way data binding and uses the term to describe a way to write dynamic HTML using HTML. A set of platform technologies and "prollyfills" enable this behavior:

• HTML Template element (<template>)
• Template Bindings (prollyfill) - describes how <template> manages instance fragments.
• Node.bind() (prollyfill) - describes how DOM nodes are bound to data values.
• Object.observe()
• Mutation Observers

When used together, these primitives extend HTML and the DOM APIs to support a sensible
separation between the UI (DOM) of application and its underlying data (model). Updates to the model are reflected in the DOM and user input into the DOM is immediately assigned to the model.

The basics Copy Chapter

{{site.project_title}}'s data-binding features hinge on the <template> element and double mustache {%raw%}{{}}{%endraw%} syntax.

• Expressions
• Filters

An example Copy Section

There's plenty of detail, but it all hinges on the <template> element. Let's walk through a simple example which demonstrates the basics.

{%raw%}

<template>
    
      <template id="greeting" repeat="{{s in salutations}}">
        <li>{{s.what}}: </li>
      </template>
    
  </template>
  <script>
    Polymer('greeting-tag', {
      ready: function() {
        this.salutations = [
          {what: 'Hello', who: 'World'},
          {what: 'GoodBye', who: 'DOM APIs'},
          {what: 'Hello', who: 'Declarative'},
          {what: 'GoodBye', who: 'Imperative'}
        ];
      }
    });
  </script>

{%endraw%}

{%comment%}

<template id="greeting" repeat="{{ salutations }}">
    <li>{{ what }}: </li>
  </template>

<script>
var t = document.getElementById('greeting');
var model = {
  salutations: [
    { what: 'Hello', who: 'World' },
    { what: 'GoodBye', who: 'DOM APIs' },
    { what: 'Hello', who: 'Declarative' },
    { what: 'GoodBye', who: 'Imperative' }
  ]
};
t.model = model;

// Needed to detect model changes if Object.observe() is not available.
Platform.performMicrotaskCheckpoint();
</script>

{%endcomment%}

This example should look mostly familiar to anyone who knows HTML, but there are a couple novel things going on:

The `