Async CSS Plugin

Browsers load CSS files (stylesheets) synchronously such that rendering of a page is delayed until all linked stylesheets have been downloaded. This behavior is typically desired because unstyled HTML is not something you want your users to see.

However, synchronous CSS loading can also get in the way, namely when a framework like Vue bundles your single page application such that all stylesheets are linked in index.html, but none of those styles are necessary to render the page initially. One common example is when index.html is designed to quickly show a loading indicator, then load all required assets in the background to finally transition to the main page when everything is ready. With synchronous CSS downloads the rendering of the loading indicator can be delayed to the point where e.g. a mobile user is shown a white screen for many seconds before the indicator finally shows up.

This is where asynchronous CSS loading can lead to a manifold decrease of the time to First Paint and thus to a much better perceived responsiveness of your site.

Prerequisites

This plugin is designed for applications that are built using webpack. More specifically, your application must satisfy one of the following conditions:

• Your application is built using webpack directly or a framework that allows for the configuration of webpack with webpack.config.js.
• Your application is built using a framework like Vue that "abstracts away" webpack.config.js but provides a different way to modify the webpack configuration.

Getting Started

Installation

npm install async-css-plugin --save-dev

Configuration

AsyncCssPlugin configuration depends on how your project is set up, please see Prerequisites for more information.

webpack.config.js

If your project does not yet contain webpack.config.js, please create one in the same folder as package.json. Otherwise, please modify accordingly. AsyncCssPlugin depends on HtmlWebpackPlugin, so webpack.config.js should minimally look as follows:

const HtmlWebpackPlugin = require('html-webpack-plugin')
const AsyncCssPlugin = require("async-css-plugin");

module.exports = {
    plugins: [
        new HtmlWebpackPlugin(),
        new AsyncCssPlugin({ /* options */ })
    ]
};

vue.config.js

If your Vue project does not yet contain vue.config.js, please create one in the same folder as package.json. Otherwise, please adapt accordingly:

const AsyncCssPlugin = require("async-css-plugin");

module.exports = {
    chainWebpack: config => {
        config.plugin("async-css-plugin").use(AsyncCssPlugin, [{ /* options */ }]);
    }
}

By default, Vue internally already uses HtmlWebpackPlugin, so there should be no need to configure that in vue.config.js.

Usage

Once webpack is configured as detailed above, stylesheet links in the generated HTML will look similar to the following:

<link href=app.cfadf482.css rel=stylesheet media=print onload="this.media='all'">

For details on why and how this works, please see The Simplest Way to Load CSS Asynchronously by the filament group.

As mentioned above, async CSS loading only makes sense when the CSS being loaded does not affect the currently visible page. It is your responsibility to show a different page (e.g. a loading indicator) while this happens, check out Net Worth for an example.

Options

The AsyncCssPlugin constructor accepts an (optional) Options object.

Credits

This plugin was inspired by async-stylesheet-webpack-plugin.