Script Extension for HTML Webpack Plugin
Deprecation Warning
tl;dr
This project is no longer maintained. It does not support Webpack 5.
A bit more detail
Any look at the project activity will show that I have not been able to maintain this project adequately.
The advent of version 5 of Webpack requires another bout of refactoring that I simply have no time for.
Consequently v2.15.0 will be the last version of this plugin.
My thanks to all users, and especially to all contributors, of this plugin over the years.
My apologies to all those whose webpack 5 migration has been made more complicated by this decision.
But I still want to use the plugin...
Feel free!
My last update works with versions of v4.44.2 of webpack and v4.5.0 of html-webpack-plugin.
Forkers feel free! That's what the licence is for.
In fact, if you fork with an intention to support on-going development, let me know!
I'll happily link to your repository here and offer some tips (main one: ditch backward compatibility - it's a pain).
I will formally archive this repository at the end of the 2020.
Summary
Enhances html-webpack-plugin functionality with different deployment options for your scripts including:
async
attribute;defer
attribute;type="module"
attribute;- any custom attributes you wish to add;
- inlining;
preload
resource hint;prefetch
resource hint
This is an extension plugin for the webpack plugin html-webpack-plugin - a plugin that simplifies the creation of HTML files to serve your webpack bundles.
The raw html-webpack-plugin incorporates all webpack-generated javascipt as synchronous<script>
elements in the generated html. This plugin allows you to:
- add standard and custom attributes to these elements;
- inline the code in the elements;
- add prefetch and preload resource hints for initial and dynamically loaded scripts.
Installation
You must be running webpack (1.x, 2.x, 3.x, 4.x) on node 6+. Install the plugin with npm:
$ npm install --save-dev script-ext-html-webpack-plugin
Not that you will need v3.0.6+ or v4.x of html-webpack-plugin
For those requiring earlier versions of node, please use the last 1.x version of this plugin. However please note this does not have webpack 4.x support:
$ npm install --save-dev script-ext-html-webpack-plugin@1.8.8
You may see an UNMET PEER DEPENDENCY
warnings for webpack and various plugins.
This is fine; in testing, we dynamically download multiple versions of webpack (via the dynavers module).
Basic Usage
Add the plugin to your webpack config as follows:
plugins:
The order is important - the plugin must come after HtmlWebpackPlugin.
The above configuration will actually do nothing due to the configuration defaults.
Some more useful scenarios:
All scripts set to async
:
plugins: defaultAttribute: 'async'
All scripts set to async
except 'first.js' which is sync:
plugins: sync: 'first.js' defaultAttribute: 'async'
Configuration offers much more complex options:
Configuration
You must pass a hash of configuration options to the plugin to cause the addition of attributes:
inline
: a script matching pattern defining scripts that should be inlined in the html (default:[]
);sync
: a script matching pattern defining script names that should have no attribute (default:[]
);async
: a script matching pattern defining script names that should have anasync
attribute (default:[]
);defer
: a script matching pattern defining script names that should have adefer
attribute (default:[]
);defaultAttribute
:'sync' | 'async' | 'defer'
The default attribute to set -'sync'
actually results in no attribute (default:'sync'
);module
: a script matching pattern defining script names that should have atype="module"
attribute (default:[]
);preload
: a script matching pattern defining scripts that should have accompanying preload resource hints (default:[]
);prefetch
: a script matching pattern defining scripts that should have accompanying prefetch resource hints (default:[]
);custom
: a single hash or an array of hashes with the following structure:test
: a script matching pattern defining scripts that should have a custom attribute added;attribute
: aString
attribute to add;value
: (optional) aString
value for the attribute; if not set the attribute has no value set (equivalent oftrue
).
A script matching pattern matches against a script's name. It can be one of:
- a
String
- matches if it is a substring of the script name; - a
RegExp
; - an array of
String
's and/orRegExp
's - matches if any one element matches; - a hash with property
test
with a value of one of the above.
In more complicated use cases it may prove difficult to ensure that the pattern matching for different attributes are mutually exclusive. To prevent confusion, the plugin operates a simple precedence model:
-
if a script name matches the
inline
script matching pattern, it will be inlined; -
if a script name matches the
sync
script matching pattern, it will have no attribute, unless it matched condition 1; -
if a script name the
async
script matching pattern, it will have theasync
attribute, unless it matched conditions 1 or 2; -
if a script name matches the
defer
script matching pattern, it will have thedefer
attribute, unless it matched conditions 1, 2 or 3; -
if a script name does not match any of the previous conditions, it will have the `defaultAttribute' attribute.
The module
attribute is independent of conditions 2-5, but will be ignored if the script isinlined.
Dynamically Loaded Scripts
The preload
and prefetch
configuration also have allow an additional property in the hash form that can be passed to include dynamically loaded (asynchronous) scripts. This property is chunks
and can have one of the following String
values:
initial
: default behaviour, no asynchronour scripts;async
: only asynchronouse scripts;all
: all scripts Note that you must still supply atest
script matching pattern which is also applied when selecting scripts.
Configuration Examples
All scripts with 'important' in their name are sync and all others set to defer
:
plugins: sync: 'important' defaultAttribute: 'defer'
Alternatively, using a regular expression:
plugins: sync: /important/ defaultAttribute: 'defer'
All scripts with 'mod' in their name are async and type 'module', all others are sync (no explicit setting for this as it is the default):
plugins: async: 'mod' module: 'mod'
Script 'startup.js' is inlined whilst all other scripts are async and preloaded:
plugins: inline: 'startup' preload: /\.js$/ defaultAttribute: 'async'
All scripts are preloaded with a crossorigin
attribute set to enable CDN's:
plugins: custom: test: /\.js$/ attribute: 'crossorigin' value: 'anonymous' preload: test: /\.js$/
All asynchronous scripts are added as preload
resource hints. All other scripts are async
:
plugins: async: /\.js$/ preload: test: /\.js$/ chunks: 'async'
All scripts have custom attribute type='text/paperscript'
and ui.js also has a custom attribute of id='1235'
:
plugins: custom: test: /\.js$/ attribute: 'type' value: 'text/paperscript' test: 'ui.js' attribute: 'id' value: '12345'
And so on, to craziness:
plugins: inline: 'startup' sync: /imp{1,3}}/ 'initial' defer: 'slow' /big.*andslow/ module: /^*/ 'mod' prefetch: 'indirectly-referenced.js' defaultAttribute: 'async'
Any problems with real-world examples, just raise an issue.
A Note on Script Names
In the above examples the actual script names are used to select the deployment option. You may not wish to couple asset names to your deployment like this. Instead you can use Webpack's entry configuration to create aliases that the plugin will then use for its pattern matching. Your webpack.config.js
will look something like this:
entry: a: path b: path c: pathoutput: ... filename: '[name].js'plugins: inline: 'c' defer: 'a' 'b'
Inlining
Several notes and caveats apply:
- This feature is for
<script>
's only. If you wish to inline css please see the sister plugin style-ext-html-webpack-plugin. - Even the simplest script will be wrapped with webpack boilerplate; ensure you minify your javascript if you want your output html to be legible!
- Hot replacement of inlined scripts will only work if caching is switched off for html-webpack-plugin:
plugins: cache: false inline: 'myinlinedscript.js'
- An alternative approach, based on jade templates is illustrated in the HtmlWebpackPlugin inline example.
Resource Hints
In most cases, modern browsers will intelligently preload referenced script assets.
However if you wish, this plugin can add resource hint elements to the <head>
element of the form:
Use the preload
and prefetch
configuration options.
Where preload
and prefetch
patterns overlap, preload
takes precedence.
Possibly a more compelling use case is to preload/prefetch dynamically loaded scripts generated by Webpack's code splitting. Since v1.7.0, this plugin can do this - see 'Dynamically Loaded Scripts' above.
Notes:
- custom attributes will be added to resource hints with the same script matching pattern. This is useful for adding such attributes as
crossorigin="anonymous"
- see the Configuration Examples above; - for more on resource hints, see the
w3c
definition; - for a more complete solution that allows the preloading\fetching of assets other than scripts, see the resource-hints-webpack-plugin.
Change History
v2.1.5
- end of life version
- updated all dependencies
- fixes some tests to accomodate change in html-webpack-plugin output
- added end-of-life section to README.
v2.1.x
- support for changes in html-webpack-plugin 4.x since alpha and beta
- custom attributes now added to resource hints too (see pull request 53 for discussion)
- update dependencies
v2.0.x
- support html-webpack-plugin 4.x - huge thanks to @snadn
- support webpack 4.x - huge thanks to @sherlock1982
- node 9.x 10,x, 11.x testing
- remove support for node 4.x and 5.x
- remove Appveyor config
- temporary remove Handlebars test until loader supports webpack 4.x
v1.8.x
- added custom attributes - now works on inline scripts as well e.g. for CSP nonces, -thanks @niieani and @phallguy
- compatible with webpack-config - thanks @avaly
- node v8+ and webback 3.x testing
- resource hints handle public paths without end separators - thanks @albv
- updated dependencies (including dev and peer) - thanks @ai, @malikshahzad228
- windows-proofed public paths - thanks @mstijak, @Jesseyx
- added appveyor support for windows build and testing - CURRENTLY SWITCHED OFF
v1.7.x
- updated for Webpack 2.5.x and updated all dependencies
- adds asynchronous script resource hints
- fixed issue 13 - inline functionality not working with HtmlWebpackPlugin hashing
- fixed issue 16 - unnecessary closing tag
- fixed issue 18 - added defensive coding against unpopulated event arguments
- refactored for better handling of
publicPath
- thanks @koalaink
v1.6.x
- works with webpack 2.2.1
- enhanced API (no need to use array), fully backwardly compatible
- refactor in preparation for v2
v1.5.x
- added resource hints
- works with webpack 2.2.0
v1.4.x
- updated internal mechanism to use new(ish) HtmlWebpackPlugin event
- improved test mechanism and enhanced test coverage
- added support for
publicPath
for inline scripts - thanks @JustAboutJeff - works with 'webpack -p' - thanks @brandongoode
v1.3.x
- added
type="text/javascript"
by default, in response to Safari 9.1.1 bug - removed experimental status of inline option
- added weback 2.2.x beta support
v1.2.x
- added inline option
v1.1.x
- added
type="module"
option
v1.0.x
- initial release