Home

Awesome

minimalcss

Build status NPM version styled with prettier Renovate enabled

A Node library to extract the minimal CSS used in a set of URLs with puppeteer. Used to find what minimal CSS is needed to render on first load, even with document.onload executed.

This minimal CSS is also known as critical path CSS and ultimately a web performance technique to make web pages load faster at initial load.

What does it do

You supply a list of URLs that it opens (one at a time) and for each page it downloads all external CSS files (e.g. <link rel="stylesheet" href="bootstrap.min.css">) and uses the DOM and document.querySelector to investigate which selectors, in the CSS, are actually in the DOM. That minimal payload of CSS is all you need to load the URLs styled without having to make it block on CSS.

Under the hood it relies on the excellent puppeteer library which uses the Headless Chome Node API. This means it runs (at the time of writing) Chrome 62 and this library is maintained by the Google Chrome team.

The CSS to analyze (and hopefully minimize) is downloaded automatically just like a browser opens and downloads CSS as mentioned in the DOM as <link> tags.

The CSS is parsed by CSSTree and the minification and compression is done with CSSO. An AST of each CSS payload is sent into the Headless Chrome page evaluation together with a callback that compares with the DOM and then each minimal CSS payload is concatenated into one big string which then CSSO compresses into one "merged" and minified CSS payload.

Usage

Install:

yarn add minimalcss --dev

You can install it globally if you like:

yarn global add minimalcss

npm install [--save-dev|--global] minimalcss

Now you can run it:

./node_modules/.bin/minimalcss https://example.com/ https://example.com/aboutus > minimal.min.css

Prior art

minimalcss isn't the first library to perform this task. What's unique and special about minimalcss is that it uses the Chrome Headless browser.

Killer features

Help needed

Let's make this a thriving community project!

Help needed with features, tooling, and much testing in real web performance optimization work.

API

const minimalcss = require('minimalcss');

Get version minimalcss.version

Just prints out the current version.

Run a minimization minimalcss.run(options)

Returns a promise. The promise returns an object containing, amongst other things, the minified minimal CSS as a string. For example:

minimalcss
  .minimize({ url: 'https://example.com/' })
  .then(result => {
    console.log('OUTPUT', result.finalCss.length, result.finalCss);
  })
  .catch(error => {
    console.error(`Failed the minimize CSS: ${error}`);
  });

That result object that is returned by the minimize function contains:

Optionally, you can supply a list of URLs like this:

minimalcss
  .minimize({ urls: ['https://example.com/page1', 'https://example.com/page2'] })
  ...

and minimalcss will try to merge the minimal critical CSS across all pages. But we aware that this can be "dangerous" because of the inherit order of CSS.

API Options

Calling minimalcss.run(options) takes an object whose only mandatory key is urls or url. Other optional options are:

Warnings

Google Fonts

Suppose you have this in your HTML:

<link href="https://fonts.googleapis.com/css?family=Lato" rel="stylesheet">

then, minimalcss will consider this an external CSS stylesheet, load it and include it in the minimal CSS.

The problem is that Google Fonts will respond to that URL dynamically based on the user agent. In other words a different CSS payload depending on who's asking. So, the user agent when minimalcss runs will be whatever puppeteer uses and it might not be the best CSS for other user agents. So to avoid this predicament use the skippable option. On the command line you can do that like this:

./node_modules/.bin/minimalcss --skip fonts.googleapis.com https://example.com

With the API, you can do it like this:

minimalcss
  .minimize({
    url: 'https://example.com',
    skippable: request => {
      return !!request.url().match('fonts.googleapis.com');
    }
  })
  .then(result => {
    ...
  });

Multiple URLs

minimalcss can accept multiple URLs when figuring out the minimal CSS for all those URLs, combined. But be careful, this can be dangerous. If you have one URL with this HTML:

<head>
  <link rel="stylesheet" href="base.css">
  <link rel="stylesheet" href="specific.css">
</head>

and another URL with...:

<head>
  <link rel="stylesheet" href="base.css">
</head>

When combining these, it will optimize the CSS in this order:

  1. base.css
  2. specific.css
  3. base.css

But if specific.css was meant to override something in base.css in the first URL, that might get undone when base.css becomes the last CSS to include.

See this issue for another good example why running minimalcss across multiple URLs.

About cheerio

When minimalcss evaluates each CSS selector to decide whether to keep it or not, some selectors might not be parseable. Possibly, the CSS employs hacks for specific browsers that cheerio doesn't support. Or there might be CSS selectors that no browser or tool can understand (e.g a typo by the CSS author). If there's a problem parsing a CSS selector, the default is to swallow the exception and let the CSS selector stay.

Also by default, all these warnings are hidden. To see them use the --debug flag (or debug API option). Then the CSS selector syntax errors are printed on stderr.

About @font-face

minimalcss will remove any @font-face rules whose name is not mentioned in any of the CSS selectors. But be aware that you might have a @font-face { font-family: MyName; } in some /static/foo.css but separately you might have an inline style sheet that looks like this:

<style type="text/css">
div.something { font-family: MyName; }
</style>

In this case the @font-face { font-family: MyName; } would be removed even though it's mentioned from somewhere else.

About Blobs

If your document uses Blob to create injectable stylesheets into the DOM, minimalcss will not be able to optimize that. It will be not be included in the final CSS.

Development

First thing to get started, once you've cloned the repo is to install all the dependencies:

yarn

Testing

Testing is done with jest. At the beginning of every test, a static file server is started on localhost and a puppeteer browser instance is created for every test.

To run the tests:

yarn jest

Best way to get into writing tests is to look at existing tests and copy.

Prettier

All code is expected to conform with Prettier according to the the .prettierrc file in the root of the project.

To check that all your code conforms, run:

yarn lintcheck

Use without a server

This blog post demonstrates technique to use minimalcss when you don't yet have a server. Using the http-server package you can start a server right before you run and shut down as soon as you're done.

License

Copyright (c) 2017-2020 Peter Bengtsson. See the LICENSE file for license rights and limitations (MIT).