hub / github.com/addyosmani/critical

github.com/addyosmani/critical @v8.0.0 sqlite

repository ↗ · DeepWiki ↗ · release v8.0.0 ↗

89 symbols 395 edges 16 files 11 documented · 12%

README

[![NPM version][npm-image]][npm-url] [![Build Status][ci-image]][ci-url] [![Coverage][coveralls-image]][coveralls-url]

critical

Critical extracts & inlines critical-path (above-the-fold) CSS from HTML

Preview

Install

pnpm add -D critical

Build plugins

grunt-critical
Gulp users should use Critical directly
For Webpack use html-critical-webpack-plugin

Demo projects

Usage

Include:

import { generate } from "critical";

Full blown example with available options:

generate({
  // Inline the generated critical-path CSS
  // - true generates HTML
  // - false generates CSS
  inline: true,

  // Your base directory
  base: "dist/",

  // HTML source
  html: "<html>...</html>",

  // HTML source file
  src: "index.html",

  // Your CSS Files (optional)
  css: ["dist/styles/main.css"],

  // Viewport width
  width: 1300,

  // Viewport height
  height: 900,

  // Output results to file
  target: {
    css: "critical.css",
    html: "index-critical.html",
    uncritical: "uncritical.css",
  },

  // Extract inlined styles from referenced stylesheets
  extract: true,

  // ignore CSS rules
  ignore: {
    atrule: ["@font-face"],
    rule: [/some-regexp/],
    decl: (node, value) => /big-image\.png/.test(value),
  },
});

Generate and inline critical-path CSS

Basic usage:

generate({
  inline: true,
  base: "test/",
  src: "index.html",
  target: "index-critical.html",
  width: 1300,
  height: 900,
});

Generate critical-path CSS

Basic usage:

generate({
  base: "test/",
  src: "index.html",
  target: "styles/main.css",
  width: 1300,
  height: 900,
});

Generate and minify critical-path CSS:

generate({
  base: "test/",
  src: "index.html",
  target: "styles/styles.min.css",
  width: 1300,
  height: 900,
});

Generate, minify and inline critical-path CSS:

generate({
  inline: true,
  base: "test/",
  src: "index.html",
  target: {
    html: "index-critical.html",
    css: "critical.css",
  },
  width: 1300,
  height: 900,
});

Generate and return output via callback:

generate({
    base: 'test/',
    src: 'index.html',
    width: 1300,
    height: 900,
    inline: true
}, (err, {css, html, uncritical}) => {
    // You now have critical-path CSS as well as the modified HTML.
    // Works with and without target specified.
    ...
});

Generate and return output via promise:

generate({
  base: "test/",
  src: "index.html",
  width: 1300,
  height: 900,
})
  .then(({ css, html, uncritical }) => {
    // You now have critical-path CSS as well as the modified HTML.
    // Works with and without target specified.
  })
  .catch((err) => {
    // …
  });

Generate and return output via async function:

const { css, html, uncritical } = await generate({
  base: "test/",
  src: "index.html",
  width: 1300,
  height: 900,
});

Generate critical-path CSS with multiple resolutions

When your site is adaptive and you want to deliver critical CSS for multiple screen resolutions this is a useful option. note: (your final output will be minified as to eliminate duplicate rule inclusion)

generate({
  base: "test/",
  src: "index.html",
  target: {
    css: "styles/main.css",
  },
  dimensions: [
    {
      height: 200,
      width: 500,
    },
    {
      height: 900,
      width: 1200,
    },
  ],
});

Generate critical-path CSS and ignore specific selectors

This is a useful option when you e.g. want to defer loading of webfonts or background images.

generate({
  base: "test/",
  src: "index.html",
  target: {
    css: "styles/main.css",
  },
  ignore: {
    atrule: ["@font-face"],
    decl: (node, value) => /url\(/.test(value),
  },
});

Generate critical-path CSS and specify asset rebase behaviour

generate({
  base: "test/",
  src: "index.html",
  target: {
    css: "styles/main.css",
  },
  rebase: {
    from: "/styles/main.css",
    to: "/folder/subfolder/index.html",
  },
});

generate({
  base: "test/",
  src: "index.html",
  target: {
    css: "styles/main.css",
  },
  rebase: (asset) => `https://my-cdn.com${asset.absolutePath}`,
});

Options

Name	Type	Default	Description
inline	`boolean`\|`object`	`false`	Inline critical-path CSS using filamentgroup's loadCSS. Pass an object to configure `inline-critical`
base	`string`	`path.dirname(src)` or `process.cwd()`	Base directory in which the source and destination are to be written
html	`string`		HTML source to be operated against. This option takes precedence over the `src` option.
css	`array`	`[]`	An array of paths to css files, file globs, Vinyl file objects or source CSS strings.
src	`string`		Location of the HTML source to be operated against
target	`string` or `object`		Location of where to save the output of an operation. Use an object with 'html' and 'css' props if you want to store both
width	`integer`	`1300`	Width of the target viewport
height	`integer`	`900`	Height of the target viewport
dimensions	`array`	`[]`	An array of objects containing height and width. Takes precedence over `width` and `height` if set
extract	`boolean`	`false`	Remove the inlined styles from any stylesheets referenced in the HTML. It generates new references based on extracted content so it's safe to use for multiple HTML files referencing the same stylesheet. Use with caution. Removing the critical CSS per page results in a unique async loaded CSS file for every page. Meaning you can't rely on cache across multiple pages
inlineImages	`boolean`	`false`	Inline images
assetPaths	`array`	`[]`	List of directories/urls where the inliner should start looking for assets
maxImageFileSize	`integer`	`10240`	Sets a max file size (in bytes) for base64 inlined images
rebase	`object` or `function`	`undefined`

Core symbols most depended-on inside this repo

Shape

Function 80

Class 6

Method 3

Languages

TypeScript100%

Modules by API surface

src/file.js43 symbols

src/errors.js9 symbols

test/helper/index.js7 symbols

cli.js6 symbols

test/array.test.js4 symbols

src/core.js4 symbols

src/array.js4 symbols

test/cli.test.js3 symbols

test/blackbox.test.js3 symbols

test/index.test.js2 symbols

src/config.js2 symbols

index.js2 symbols

Dependencies from manifests, versioned

@adobe/css-tools4.4.4 · 1×

@vitest/coverage-v84.1.6 · 1×

async3.2.6 · 1×

async-traverse-tree1.1.1 · 1×

clean-css5.3.3 · 1×

common-tags1.8.2 · 1×

css-url-parser1.1.4 · 1×

data-uri-to-buffer8.0.0 · 1×

debug4.4.3 · 1×

finalhandler2.1.1 · 1×

find-up8.0.0 · 1×

get-port7.2.0 · 1×

For agents

$ claude mcp add critical \
  -- python -m otcore.mcp_server <graph>

⬇ download graph artifact