❤
npm
Sign UpSign In

metalsmith-inline-critical-css
TypeScript icon, indicating that this package has built-in type declarations

0.4.0 • Public • Published

metalsmith-inline-critical-css

A Metalsmith plugin to inspect HTML files, inline used selectors from specified CSS, and load the rest asynchronously.

npm npm downloads dependencies

Motivation

When the browser encounters a <link rel="stylesheet"> in the <head>, it pauses, goes to the network, fetches the file, and only then continues. This is called "render blocking". If it sounds bad for performance, it's because it is! This is especially true for slower networks where the latency alone can add seconds to the request.

To combat this, you can "inline" the used or critical CSS for a page as a <style> tag. You then load the rest asynchronously. To do that, you link the stylesheet as <link rel="preload">, which decouples downloading from execution, and allows the browser to continue. Once the stylesheet has loaded, it is "swapped in". To account for browsers that do not support rel="preload", we use the excellent LoadCSS relpreload.js.

Inlining the critical CSS for a page is one of the most important optimisations you can do to make your site paint faster!

Quick start

This package is distributed via npm.

$ npm install --save metalsmith-inline-critical-css
# or 
$ yarn add metalsmith-inline-critical-css

Then you can use the plugin in your metalsmith pipeline:

const fs = require('fs');
const path = require('path');
const metalsmith = require('metalsmith');
const criticalCss = require('metalsmith-inline-critical-css');
 
// Set these as you want for your application
const INPUT_DIR = '_site/';
const OUTPUT_DIR = '_site/';
 
function main() {
  // Run metalsmith pipeline
  metalsmith(process.cwd())
    .source(INPUT_DIR) // source directory
    .destination(OUTPUT_DIR) // destination directory
    .clean(false) // clean destination before
    .use(
      criticalCss({
        // Files to run against
        pattern: '**/*.html',
        // The CSS file whose selectors will be matched against the html
        cssFile: path.join(INPUT_DIR, hashedCssFilename),
        // The path under which the css is included in the template files
        cssPublicPath: hashedCssFilename,
      })
    )
    .build(function(err) {
      if (err) {
        console.log('Error running the metalsmith pipeline: ' + err);
        throw err;
      }
      console.log('Done!');
    });
}
 
main();

Options

interface IOptions {
  /** A multimatch pattern of files to run on. */
  pattern: string;
 
  /** The name of the css file in the metalsmith data. */
  cssFile: string;
 
  /**
   * The path under which the css is included in the template.
   * Important for knowing which <link> tag to replace.
   */
  cssPublicPath: string;
}

Credits, Thanks, Inspiration

Thanks to Filament Group for their work on Load CSS!

Readme

Keywords

Package Sidebar

Install

npm i metalsmith-inline-critical-css

Repository

github.com/fpapado/metalsmith-inline-critical-css

Homepage

github.com/fpapado/metalsmith-inline-critical-css#readme

Weekly Downloads

7

Version

0.4.0

License

MIT

Unpacked Size

26.8 kB

Total Files

8

Last publish

Collaborators

  • fpapado
Try on RunKit
Report malware