Include Assets extension for the HTML Webpack Plugin
Enhances html-webpack-plugin functionality by allowing you to specify js or css assets to be included.
When using a plugin such as copy-webpack-plugin you may have assets output to your build directory that are not detected/output by the html-webpack-plugin.
This plugin allows you to force some of these assets to be included in the output from html-webpack-plugin.
Installation
You must be running webpack on node 4.x or higher
Install the plugin with npm:
$ npm install --save-dev html-webpack-include-assets-plugin
Basic Usage
Require the plugin in your webpack config:
var HtmlWebpackIncludeAssetsPlugin = ;
Add the plugin to your webpack config as follows:
plugins: assets: append: true
Note that some users have encountered issues with plugin ordering.
It is advisable to always place any HtmlWebpackPlugin
plugins before any HtmlWebpackIncludeAssetsPlugin
plugins in your webpack config.
Options
The available options are:
-
jsExtensions
:string
orarray
Specifies the file extensions to use to determine if assets are script assets. Default is
['.js']
. -
cssExtensions
:string
orarray
Specifies the file extensions to use to determine if assets are style assets. Default is
['.css']
. -
assets
:string
orarray
orobject
Assets that will be output into your html-webpack-plugin template.
To specify just one asset, simply pass a string or object. To specify multiple, pass an array of strings or objects.
If the asset path is static and ends in one of the
jsExtensions
orcssExtensions
values, simply use a string value.If the asset is not static or does not have a valid extension, you can instead pass an object with properties
path
(required) andtype
orglob
orglobPath
orattributes
(optional). In this casepath
is the asset href/src,type
is one ofjs
orcss
, andglob
is a wildcard to use to match all files in the path (uses the glob package). TheglobPath
can be used to specify the directory from which theglob
should search for filename matches (the default is to usepath
within webpack's output directory).The
attributes
property may be used to add additional attributes to the link or script element that is injected. The keys of this object are attribute names and the values are the attribute values (string or boolean key values are allowed).The
assetPath
property may be used to specify the full path to the included asset. This can be useful as it will trigger a recompilation after the assets have changed when usingwebpack-dev-server
orwebpack-dev-middleware
in development mode. -
append
:boolean
Specifying whether the assets should be prepended (
false
) before any existing assets, or appended (true
) after them. -
resolvePaths
:boolean
Specifying whether the asset paths should be resolved with
path.resolve
(i.e. made absolute). -
publicPath
:boolean
orstring
Specifying whether the assets should be prepended with webpack's public path or a custom publicPath (
string
).A value of
false
may be used to disable prefixing with webpack's publicPath, or a value likemyPublicPath/
may be used to prefix all assets with the given string. Default istrue
. -
hash
:boolean
orfunction(assetName, hash)
Specifying whether the assets should be appended with webpack's compilation hash. This is useful for cache busting. Default is
false
. -
files
:string
orarray
Files that the assets will be added to.
By default the assets will be included in all files. If files are defined, the assets will only be included in specified file globs (uses the minimatch package).
cssAssets
:array
Optional shortcut for adding css assets. An array of css asset objects.
See the cssAssets example below for the syntax of css asset object.
Example
Using HtmlWebpackIncludeAssetsPlugin
and CopyWebpackPlugin
to include assets to html-webpack-plugin
template :
plugins: from: 'node_modules/bootstrap/dist/css' to: 'css/' from: 'node_modules/bootstrap/dist/fonts' to: 'fonts/' assets: 'css/bootstrap.min.css' 'css/bootstrap-theme.min.css' append: false
Appending and prepending at the same time :
plugins: from: 'node_modules/bootstrap/dist/css' to: 'css/' from: 'node_modules/bootstrap/dist/fonts' to: 'fonts/' assets: 'css/bootstrap.min.css' 'css/bootstrap-theme.min.css' append: false assets: 'css/custom.css' append: true
Using custom jsExtensions
:
plugins: assets: 'dist/output.js' 'lib/content.jsx' append: false jsExtensions: '.js' '.jsx'
Using custom publicPath
:
plugins: from: 'node_modules/bootstrap/dist/css' to: 'css/' from: 'node_modules/bootstrap/dist/fonts' to: 'fonts/' assets: 'css/bootstrap.min.css' 'css/bootstrap-theme.min.css' append: false publicPath: 'myPublicPath/'
Or to include assets without prepending the publicPath
:
plugins: assets: 'css/no-public-path.min.css' 'http://some.domain.com.js' append: false publicPath: false
Manually specifying asset types :
plugins: from: 'node_modules/bootstrap/dist/css' to: 'css/' from: 'node_modules/bootstrap/dist/fonts' to: 'fonts/' assets: '/css/bootstrap.min.css' '/css/bootstrap-theme.min.css' path: 'https://fonts.googleapis.com/css?family=Material+Icons' type: 'css' append: false publicPath: ''
Adding custom attributes to asset tags :
The bootstrap-theme link tag will be given an id="bootstrapTheme" attribute.
plugins: from: 'node_modules/bootstrap/dist/css' to: 'css/' from: 'node_modules/bootstrap/dist/fonts' to: 'fonts/' assets: '/css/bootstrap.min.css' path: '/css/bootstrap-theme.min.css' attributes: id: 'bootstrapTheme' append: false publicPath: ''
Using hash
option :
When the hash option is set to true
, asset paths will be appended with a hash query parameter (?hash=<the_hash>
)
plugins: from: 'node_modules/bootstrap/dist/css' to: 'css/' from: 'node_modules/bootstrap/dist/fonts' to: 'fonts/' assets: 'css/bootstrap.min.css' 'css/bootstrap-theme.min.css' append: false hash: true
When the hash option is set to a function
, asset paths will be replaced with the result of executing that function
plugins: from: 'somepath/somejsfile.js' to: 'js/somejsfile.[hash].js' from: 'somepath/somecssfile.css' to: 'css/somecssfile.[hash].css' assets: path: 'js' glob: '*.js' globPath: 'somepath' assets: path: 'css' glob: '*.css' globPath: 'somepath' append: false { assetName = assetName; assetName = assetName; return assetName; }
Specifying specific files
plugins: from: 'node_modules/bootstrap/dist/css' to: 'css/' from: 'node_modules/bootstrap/dist/fonts' to: 'fonts/' filename: 'a/index.html' filename: 'b/index.html' files: 'a/**/*.html' assets: 'css/a.css' append: true files: 'b/**/*.html' assets: 'css/b.css' append: true
Specifying assets usings a glob
Note that since copy-webpack-plugin
does not actually copy the files to webpack's output directory until after html-webpack-plugin
has completed, it is necessary to use the globPath
to retrieve filename matches relative to the original location of any such files.
plugins: from: 'node_modules/bootstrap/dist/css' to: 'css/' from: 'node_modules/bootstrap/dist/fonts' to: 'fonts/' assets: path: 'css' glob: '*.css' globPath: 'node_modules/bootstrap/dist/css/' append: true
Specifying cssAssets
(a shortcut for specifying assets of type css)
output: publicPath: '/my-public-path/'plugins: from: 'node_modules/bootstrap/dist/css' to: 'css/' from: 'node_modules/bootstrap/dist/fonts' to: 'fonts/' assets: append: true cssAssets: href: 'asset/path' attributes: rel: 'icon' href: '/absolute/asset/path' asset: false attributes: rel: 'manifest'
Will append the following link elements into the index template html
<!-- previous header content -->
Note that the second cssAsset's href was not prefixed with the webpack publicPath
because csAsset.asset
was set to false
.