async-stylesheet-webpack-plugin

Loading stylesheets asynchronously

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
async-stylesheet-webpack-plugin
0.4.16 years ago6 years agoMinified + gzip package size for async-stylesheet-webpack-plugin in KB

Popular Searches

Readme

license Build Status npm version dependencies Status devDependencies Status peerDependencies Status npm
Asynchronous stylesheets loading with HTML Webpack Plugin

Why load stylesheets asynchronously?

Referencing CSS stylesheets with link[rel=stylesheet] or @import causes browsers to delay page rendering while a stylesheet loads. When loading stylesheets that are not critical to the initial rendering of a page, this blocking behavior is undesirable. The new <link rel="preload"> standard enables us to load stylesheets asynchronously, without blocking rendering.

Install via npm

npm install --save-dev async-stylesheet-webpack-plugin

  • Latest release: https://github.com/devpreview/async-stylesheet-webpack-plugin/releases
  • NPM: https://www.npmjs.com/package/async-stylesheet-webpack-plugin

Usage

The plugin will update all your webpack bundles stylesheets in the head using link tags with rel="preload" attribute. Just add the plugin to your webpack config as follows:
webpack.config.js 
const HtmlWebpackPlugin = require('html-webpack-plugin')
const AsyncStylesheetWebpackPlugin = require('async-stylesheet-webpack-plugin');

module.exports = {
  ...
  
  plugins: [
    new HtmlWebpackPlugin(),
    new AsyncStylesheetWebpackPlugin(),
    ...
  ]
}

This will generate a file dist/index.html containing the following:
<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <title>Webpack App</title>
    <link href="app.css" rel="preload" as="style" onload="this.onload=null;this.rel='stylesheet';">
    <noscript><link href="app.css" rel="stylesheet"></noscript>
  </head>
  <body>
    <script src="app.js"></script>
  </body>
</html>

Options

You can pass a hash of configuration options to async-stylesheet-webpack-plugin. Allowed values are as follows:
|Name|Type|Default|Description| |:--:|:--:|:-----:|:----------| |preloadPolyfill|{Boolean}|false|If true then enabled legacy browser support| |noscriptFallback|{Boolean}|true|If true then enabled fallback stylesheets loading without JavaScript| |chunks|{String[]}|null|Allows you to async load only some chunks| |excludeChunks|{String[]}|null|Allows you to skip async load some chunks|
Here's an example webpack config illustrating how to use these options:
webpack.config.js 
module.exports = {
  ...
  
  plugins: [
    new HtmlWebpackPlugin(),
    new AsyncStylesheetWebpackPlugin({
      preloadPolyfill: true,
      noscriptFallback: true
    }),
    ...
  ]
}

Legacy browser support

Preload polyfill

If preloadPolyfill option is enabled (this option disabled by default) async-stylesheet-webpack-plugin adding in HTML head cssrelpreload.js provided by loadCSS.
This will generate a file dist/index.html containing the following:
<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <title>Webpack App</title>
    <script type="text/javascript">/* here is the content of the cssrelpreload.js */</script>
    <link href="app.css" rel="preload" as="style" onload="this.onload=null;this.rel='stylesheet';">
    <noscript><link href="app.css" rel="stylesheet"></noscript>
  </head>
  <body>
    <script src="app.js"></script>
  </body>
</html>

Without JavaScript

If noscriptFallback option is enabled (this option enabled by default) async-stylesheet-webpack-plugin adding in HTML head noscript tag with traditional stylesheet loading.
This will generate a file dist/index.html containing the following: 
<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <title>Webpack App</title>
    <link href="app.css" rel="preload" as="style" onload="this.onload=null;this.rel='stylesheet';">
    <noscript><link href="app.css" rel="stylesheet"></noscript>
  </head>
  <body>
    <script src="app.js"></script>
  </body>
</html>

If noscriptFallback option is disabled async-stylesheet-webpack-plugin only updated link tags: 
<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <title>Webpack App</title>
    <link href="app.css" rel="preload" as="style" onload="this.onload=null;this.rel='stylesheet';">
  </head>
  <body>
    <script src="app.js"></script>
  </body>
</html>

Credit

  • loadCSS - A function for loading CSS asynchronously;
  • HTML Webpack Plugin - Simplifies creation of HTML files to serve your webpack bundles.

See also

Need a feature?

Welcome to issues!