Package Exports

html-webpack-include-assets-plugin

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (html-webpack-include-assets-plugin) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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.

Prior Version

html-webpack-include-assets-plugin version 2.x and above require ** Node >= 8.6 **
For older version of Node, please install version 1.x and consult the old readme

Motivation

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 plugins gives you the tools to fix that and also lets you inject the webpack publicPath or compilation hash into your assets paths if you so choose.

Installation

You must be running webpack on node 8.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 = require('html-webpack-include-assets-plugin');

Add the plugin to your webpack config:

output: {
  publicPath: '/abc/'
},
plugins: [
  new HtmlWebpackPlugin(),
  new HtmlWebpackIncludeAssetsPlugin({ assets: ['a.js', 'b.css'], append: true })
]

Which will generate html like this:

<head>
  <!-- other head content -->
  <link rel="stylesheet" href="/abc/b.css"/>
</head>
<body>
  <!-- other body content -->
  <script type="text/javascript" src="/abc/a.js"></script>
</body>

Options

The available options are:

jsExtensions:string|array - The file extensions to use when attempting to determine if an assets object is a script.
cssExtensions:string|array - The file extensions to use when attempting to determine if an assets object is a link.
append:boolean - Use true to append assets or false to prepend assets.
publicPath: boolean or string, or function(path:string, publicPath:string) => any:string - (default true)
- Determines hether the assets should be prepended with webpack's public path or a custom publicPath (string or function).
- A value of false may be used to disable prefixing with webpack's publicPath, or a value like myPublicPath/ may be used to prefix all assets with the given string. Default is true.
hash: boolean or function(path: string, hash: string) => any: string - (default false)

Specifying whether the assets should be appended with webpack's compilation hash. This is useful for cache busting. Default is false.
files: string or array - (default [])

Files that the assets will be added to. Using this option can be necessary if you are using multiple instances of the this plugin or html-webpack-plugin plugin instances.

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).
links:string|array|object - (default []) - Shortcut to add assets that are all type css. Will be added after any assets values.
scripts:string|array|object - (default []) - Shortcut to add assets that are all type js. Will be added after any assets values.
assets:string|array|object - (default [])

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.
Assets that do not have a type attempt to infer it from the asset path using the jsExtensions and cssExtensions options values.

This plugin will throw an error if it cannot determine the type of any asset, we can specify asset as objects to fix that.
```
const oldAsset = 'abc'; // change this

const newAsset = { // to this
  path: 'abc',
  type: 'css'
}
```
Each asset object may have the following properties:

path:string (required) - The asset path.
type:string (optional) - For assets where the type is unknown, this can be set to either of: ['css', 'js'].
glob:string and globPath:string (must be together) - Lets you use a glob to insert multiple assets from the globPath.
attributes:object (optional) - The attributes to be injected into the html tags. Some attributes are filtered by html-webpack-plugin (especially for script tags). To work requires that you set the html-webpack-plugin options to: { inject: true }.
assetPath:string (optional) - property may be used to specify a source path to be added as an entry to html-webpack-plugin. This can be useful as it will trigger a recompilation after the assets have changed when using webpack-dev-server or webpack-dev-middleware in development mode.
publicPath:boolean|function(path:string, publicPath:string) => any:string (optional) - Controls whether the webpack publicPath will be injected into the asset path. true mean always. false means never. function means manual, undefined means use global settings.
hash:boolean|function(path:string, hash:string) => any:string (optional) - Controls whether the webpack compilation hash will be injected into the asset path. true mean always. false means never. function means manual, undefined means use global settings.

Examples

Using HtmlWebpackIncludeAssetsPlugin and CopyWebpackPlugin to include assets to html-webpack-plugin template :

plugins: [
  new CopyWebpackPlugin([
    { from: 'node_modules/bootstrap/dist/css', to: 'css/'},
    { from: 'node_modules/bootstrap/dist/fonts', to: 'fonts/'}
  ]),
  new HtmlWebpackPlugin(),
  new HtmlWebpackIncludeAssetsPlugin({
    assets: ['css/bootstrap.min.css', 'css/bootstrap-theme.min.css'],
    append: false
  })
]

Appending and prepending at the same time :

plugins: [
  new CopyWebpackPlugin([
    { from: 'node_modules/bootstrap/dist/css', to: 'css/'},
    { from: 'node_modules/bootstrap/dist/fonts', to: 'fonts/'}
  ]),
  new HtmlWebpackPlugin(),
  new HtmlWebpackIncludeAssetsPlugin({
    assets: ['css/bootstrap.min.css', 'css/bootstrap-theme.min.css'],
    append: false
  }),
  new HtmlWebpackIncludeAssetsPlugin({
    assets: ['css/custom.css'],
    append: true
  })
]

Using custom jsExtensions :

plugins: [
  new HtmlWebpackPlugin(),
  new HtmlWebpackIncludeAssetsPlugin({
    assets: ['dist/output.js', 'lib/content.jsx'],
    append: false,
    jsExtensions: ['.js', '.jsx']
  })
]

Using custom publicPath :

plugins: [
  new CopyWebpackPlugin([
    { from: 'node_modules/bootstrap/dist/css', to: 'css/'},
    { from: 'node_modules/bootstrap/dist/fonts', to: 'fonts/'}
  ]),
  new HtmlWebpackPlugin(),
  new HtmlWebpackIncludeAssetsPlugin({
    assets: ['css/bootstrap.min.css', 'css/bootstrap-theme.min.css'],
    append: false,
    publicPath: 'myPublicPath/'
  })
]

Or to include assets without prepending the publicPath:

plugins: [
  new HtmlWebpackPlugin(),
  new HtmlWebpackIncludeAssetsPlugin({
    assets: ['css/no-public-path.min.css', 'http://some.domain.com.js'],
    append: false,
    publicPath: false
  })
]

Manually specifying asset types :

plugins: [
  new CopyWebpackPlugin([
    { from: 'node_modules/bootstrap/dist/css', to: 'css/'},
    { from: 'node_modules/bootstrap/dist/fonts', to: 'fonts/'}
  ]),
  new HtmlWebpackPlugin(),
  new HtmlWebpackIncludeAssetsPlugin({
    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: [
  new CopyWebpackPlugin([
    { from: 'node_modules/bootstrap/dist/css', to: 'css/'},
    { from: 'node_modules/bootstrap/dist/fonts', to: 'fonts/'}
  ]),
  new HtmlWebpackPlugin(),
  new HtmlWebpackIncludeAssetsPlugin({
    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: [
  new CopyWebpackPlugin([
    { from: 'node_modules/bootstrap/dist/css', to: 'css/'},
    { from: 'node_modules/bootstrap/dist/fonts', to: 'fonts/'}
  ]),
  new HtmlWebpackPlugin(),
  new HtmlWebpackIncludeAssetsPlugin({
    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: [
  new CopyWebpackPlugin([
    { from: 'somepath/somejsfile.js', to: 'js/somejsfile.[hash].js' },
    { from: 'somepath/somecssfile.css', to: 'css/somecssfile.[hash].css' }
  ]),
  new HtmlWebpackPlugin(),
  new HtmlWebpackIncludeAssetsPlugin({
    assets: [{ path: 'js', glob: '*.js', globPath: 'somepath' }],
    assets: [{ path: 'css', glob: '*.css', globPath: 'somepath' }],
    append: false,
    hash: function(assetName, hash) {
      assetName = assetName.replace(/\.js$/, '.' + hash + '.js');
      assetName = assetName.replace(/\.css$/, '.' + hash + '.css');
      return assetName;
    }
  })
]

Specifying specific files

plugins: [
  new CopyWebpackPlugin([
    { from: 'node_modules/bootstrap/dist/css', to: 'css/'},
    { from: 'node_modules/bootstrap/dist/fonts', to: 'fonts/'}
  ]),
  new HtmlWebpackPlugin({
    filename: 'a/index.html'
  }),
  new HtmlWebpackPlugin({
    filename: 'b/index.html'
  }),
  new HtmlWebpackIncludeAssetsPlugin({
    files: ['a/**/*.html'],
    assets: ['css/a.css'],
    append: true
  }),
  new HtmlWebpackIncludeAssetsPlugin({
    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: [
  new CopyWebpackPlugin([
    { from: 'node_modules/bootstrap/dist/css', to: 'css/'},
    { from: 'node_modules/bootstrap/dist/fonts', to: 'fonts/'}
  ]),
  new HtmlWebpackPlugin(),
  new HtmlWebpackIncludeAssetsPlugin({
    assets: [{ path: 'css', glob: '*.css', globPath: 'node_modules/bootstrap/dist/css/' }],
    append: true
  })
]

Specifying links (a shortcut for specifying assets of type css)

output: {
  publicPath: '/my-public-path/'
},
plugins: [
  new CopyWebpackPlugin([
    { from: 'node_modules/bootstrap/dist/css', to: 'css/'},
    { from: 'node_modules/bootstrap/dist/fonts', to: 'fonts/'}
  ]),
  new HtmlWebpackPlugin(),
  new HtmlWebpackIncludeAssetsPlugin({
    assets: [],
    append: true,
    links: [
      {
        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

<head>
  <!-- previous header content -->
  <link rel="icon" href="/my-public-path/asset/path"/>
  <link rel="manifest" href="/absolute/asset/path"/>
</head>

Note that the second link's href was not prefixed with the webpack publicPath because csAsset.asset was set to false.

Caveats

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.

This plugin has only been tested with two instances in one webpack config, where one had option.append: false and the other had option.append: true.

It is not recommended to use more than one instance of this plugin in one webpack config unless using the above configuration.

Changing HtmlWebpackPlugin.options.inject from its default value may cause issues.

This plugin requires HtmlWebpackPlugin.options.inject to be true (it defaults to true if undefined) for attribute injection to work.

If you setup your webpack config to have HtmlWebpackPlugin.options.inject: false like this:

output: {
  publicPath: '/the-public-path/'
},
plugins: [
  new HtmlWebpackPlugin({ inject: false }),
  new HtmlWebpackIncludeAssetsPlugin({
    assets: [{ path: 'css/bootstrap-theme.min.css', attributes: { id: 'bootstrapTheme' } }],
    links: [{ href: 'the-ref', attributes: { rel: 'icon' } }],
    append: true
  })
]

You will need to add the following to your template index.html to get assets to be generated:

<head>
  <!-- other head content -->
  <% for (var cssIndex = 0; cssIndex < htmlWebpackPlugin.files.css.length; cssIndex++) { %>
    <link rel="stylesheet" href="<%= htmlWebpackPlugin.files.css[cssIndex] %>">
  <% } %>
</head>
<body>
  <!-- other body content -->
  <% for (var jsIndex = 0; jsIndex < htmlWebpackPlugin.files.js.length; jsIndex++) { %>
    <script src="<%= htmlWebpackPlugin.files.js[jsIndex] %>"></script>
  <% } %>
</body>

Using the (lodash) template syntax like this for css and js files is necessary when you turn injection off.

But, the template syntax does not allow injection of more than one attribute value.

This means it will generate an index.html that looks like this:

<head>
  <link rel="stylesheet" href="/the-public-path/css/bootstrap-theme.min.css">
  <link rel="stylesheet" href="/the-public-path/the-ref">
</head>

None of the link elements have any of the attributes we specified for the assets or links.

This is because HtmlWebpackPlugin.options.inject needs to be set to true for attributes injection to work.