❤
npm
Sign UpSign In

async-stylesheet-webpack-plugin
TypeScript icon, indicating that this package has built-in type declarations

0.4.1 • Public • Published

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

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!

Dependencies (1)

Dev Dependencies (8)

Package Sidebar

Install

npm i async-stylesheet-webpack-plugin

Repository

github.com/devpreview/async-stylesheet-webpack-plugin

Homepage

github.com/devpreview/async-stylesheet-webpack-plugin

Weekly Downloads

327

Version

0.4.1

License

MIT

Unpacked Size

23.4 kB

Total Files

6

Last publish

Collaborators

  • devpreview
Try on RunKit
Report malware