html-webpack-externals-plugin

Webpack plugin that works alongside html-webpack-plugin to use pre-packaged vendor bundles.

How it works

This plugin is very simple and just encapsulates two other Webpack plugins to do the heavy lifting. It:

modifies your Webpack config at runtime to add your vendor modules to the externals property.
runs the copy-webpack-plugin to copy your vendor module assets into the output path.
runs the html-webpack-include-assets-plugin to add your vendor module bundles to the HTML output.

Installation

npm install --save-dev html-webpack-externals-plugin

Usage

Require the plugin in your Webpack config file.

const HtmlWebpackExternalsPlugin = require('html-webpack-externals-plugin')

Then instantiate it in the plugins array, after your instance of html-webpack-plugin.

plugins: [
  new HtmlWebpackPlugin(),
  new HtmlWebpackExternalsPlugin(
    // See API section
  ),
]

API

The constructor takes a configuration object with the following properties.

Property	Type	Description	Default
`externals`	array<object>	An array of vendor modules that will be excluded from your Webpack bundle and added as `script` or `link` tags in your HTML output.	None
`externals[].module`	string	The name of the vendor module. This should match the package name, e.g. if you are writing `import React from 'react'`, this would be `react`.	None
`externals[].entry`	string \| array<string> \| object \| array<object \| string>	The path, relative to the vendor module directory, to its pre-bundled distro file. e.g. for React, use `dist/react.js`, since the file exists at `node_modules/react/dist/react.js`. Specify an array if there are multiple CSS/JS files to inject. To use a CDN instead, simply use a fully qualified URL beginning with `http://`, `https://`, or `//`. For entries whose type (JS or CSS) cannot be inferred by file extension, pass an object such as `{ path: 'https://some/url', type: 'css' }` (or `type: 'js'`).	None
`externals[].entry.path`	string	If entry is an object, the path to the asset.	None
`externals[].entry.type`	`'js'`\|`'css'`	The asset type, if it cannot be inferred.	Inferred by extension when possible
`externals[].entry.attributes`	object.<string,string>	Additional attributes to add to the injected tag.	`{}`
`externals[].global`	string \| null	For JavaScript modules, this is the name of the object globally exported by the vendor's dist file. e.g. for React, use `React`, since `react.js` creates a `window.React` global. For modules without an export (such as CSS), omit this property or use `null`.	`null`
`externals[].supplements`	array<string>	For modules that require additional resources, specify globs of files to copy over to the output. e.g. for Bootstrap CSS, use `['dist/fonts/']`, since Glyphicon fonts are referenced in the CSS and exist at `node_modules/bootstrap/dist/fonts/`.	`[]`
`externals[].append`	boolean	Set to true to inject this module after your Webpack bundles.	`false`
`hash`	boolean	Set to true to append the injected module distro paths with a unique hash for cache-busting.	`false`
`outputPath`	string	The path (relative to your Webpack `outputPath`) to store externals copied over by this plugin.	`vendor`
`publicPath`	string \| null	Override Webpack config's `publicPath` for the externals files, or `null` to use the default `output.publicPath` value.	`null`
`files`	string \| array<string> \| null	If you have multiple instances of HtmlWebpackPlugin, use this to specify globs of which files you want to inject assets into. Will add assets to all files by default.	`null`
`enabled`	boolean	Set to `false` to disable the plugin (useful for disabling in development mode).	`true`

Examples

Local JS external example

This example assumes jquery is installed in the app. It:

adds jquery to your Webpack config's externals object to exclude it from your bundle, telling it to expect a global object called jQuery (on the window object)
copies node_modules/jquery/dist/jquery.min.js to <output path>/vendor/jquery/dist/jquery.min.js
adds <script type="text/javascript" src="<public path>/vendor/jquery/dist/jquery.min.js"></script> to your HTML file, before your chunks

new HtmlWebpackExternalsPlugin({
  externals: [
    {
      module: 'jquery',
      entry: 'dist/jquery.min.js',
      global: 'jQuery',
    },
  ],
})

Local CSS external example

This example assumes bootstrap is installed in the app. It:

copies node_modules/bootstrap/dist/css/bootstrap.min.css to <output path>/vendor/bootstrap/dist/css/bootstrap.min.css
adds <link href="<public path>/vendor/bootstrap/dist/css/bootstrap.min.css" rel="stylesheet"> to your HTML file, before your chunks

new HtmlWebpackExternalsPlugin({
  externals: [
    {
      module: 'bootstrap',
      entry: 'dist/css/bootstrap.min.css',
    },
  ],
})

Local external with supplemental assets example

This example assumes bootstrap is installed in the app. It:

copies node_modules/bootstrap/dist/css/bootstrap.min.css to <output path>/vendor/bootstrap/dist/css/bootstrap.min.css
copies all contents of node_modules/bootstrap/dist/fonts/ to <output path>/vendor/bootstrap/dist/fonts/
adds <link href="<public path>/vendor/bootstrap/dist/css/bootstrap.min.css" rel="stylesheet"> to your HTML file, before your chunks

new HtmlWebpackExternalsPlugin({
  externals: [
    {
      module: 'bootstrap',
      entry: 'dist/css/bootstrap.min.css',
      supplements: ['dist/fonts/'],
    },
  ],
})

CDN example

This example does not require the jquery module to be installed. It:

adds jquery to your Webpack config's externals object to exclude it from your bundle, telling it to expect a global object called jQuery (on the window object)
adds <script type="text/javascript" src="https://unpkg.com/[email protected]/dist/jquery.min.js"></script> to your HTML file, before your chunks

new HtmlWebpackExternalsPlugin({
  externals: [
    {
      module: 'jquery',
      entry: 'https://unpkg.com/[email protected]/dist/jquery.min.js',
      global: 'jQuery',
    },
  ],
})

URL without implicit extension example

Some CDN URLs don't have file extensions, so the plugin cannot determine whether to use a link tag or a script tag. In these situations, you can pass an object in place of the entry property that specifies the path and type explicitly.

This example uses the Google Fonts API to load the Roboto font. It:

adds <link href="https://fonts.googleapis.com/css?family=Roboto" rel="stylesheet"> to your HTML file, before your chunks

new HtmlWebpackExternalsPlugin({
  externals: [
    {
      module: 'google-roboto',
      entry: {
        path: 'https://fonts.googleapis.com/css?family=Roboto',
        type: 'css',
      },
    },
  ],
})

Module with multiple entry points example

Some modules require more than one distro file to be loaded. For example, Bootstrap has a normal and a theme CSS entry point.

This example assumes bootstrap is installed in the app. It:

copies node_modules/bootstrap/dist/css/bootstrap.min.css to <output path>/vendor/bootstrap/dist/css/bootstrap.min.css
copies node_modules/bootstrap/dist/css/bootstrap-theme.min.css to <output path>/vendor/bootstrap/dist/css/bootstrap-theme.min.css
copies all contents of node_modules/bootstrap/dist/fonts/ to <output path>/vendor/bootstrap/dist/fonts/
adds <link href="<public path>/vendor/bootstrap/dist/css/bootstrap.min.css" rel="stylesheet"> to your HTML file, before your chunks
adds <link href="<public path>/vendor/bootstrap/dist/css/bootstrap-theme.min.css" rel="stylesheet"> to your HTML file, before your chunks

new HtmlWebpackExternalsPlugin({
  externals: [
    {
      module: 'bootstrap',
      entry: ['dist/css/bootstrap.min.css', 'dist/css/bootstrap-theme.min.css'],
      supplements: ['dist/fonts/'],
    },
  ],
})

Appended assets example

Sometimes you want to load the external after your Webpack chunks instead of before.

This example assumes bootstrap is installed in the app. It:

copies node_modules/bootstrap/dist/css/bootstrap.min.css to <output path>/vendor/bootstrap/dist/css/bootstrap.min.css
adds <link href="<public path>/vendor/bootstrap/dist/css/bootstrap.min.css" rel="stylesheet"> to your HTML file, after your chunks

new HtmlWebpackExternalsPlugin({
  externals: [
    {
      module: 'bootstrap',
      entry: 'dist/css/bootstrap.min.css',
      append: true,
    },
  ],
})

Cache-busting with hashes example

You can configure the plugin to append hashes to the query string on the HTML tags so that, when upgrading modules, a new hash is computed, busting your app users' caches. Do not use this in tandem with CDNs, only when using local externals.

This example assumes bootstrap is installed in the app. It:

copies node_modules/bootstrap/dist/css/bootstrap.min.css to <output path>/vendor/bootstrap/dist/css/bootstrap.min.css
adds <link href="<public path>/vendor/bootstrap/dist/css/bootstrap.min.css?<unique hash>" rel="stylesheet"> to your HTML file, before your chunks

new HtmlWebpackExternalsPlugin({
  externals: [
    {
      module: 'bootstrap',
      entry: 'dist/css/bootstrap.min.css',
    },
  ],
  hash: true,
})

Customizing output path example

By default, local externals are copied into the Webpack output directory, into a subdirectory called vendor. This is configurable.

Do not include a trailing slash or leading slash in your output path, they are concatenated automatically by the plugin.

This example assumes bootstrap is installed in the app. It:

copies node_modules/bootstrap/dist/css/bootstrap.min.css to <output path>/thirdparty/bootstrap/dist/css/bootstrap.min.css
adds <link href="<public path>/thirdparty/bootstrap/dist/css/bootstrap.min.css" rel="stylesheet"> to your HTML file, before your chunks

new HtmlWebpackExternalsPlugin({
  externals: [
    {
      module: 'bootstrap',
      entry: 'dist/css/bootstrap.min.css',
    },
  ],
  outputPath: 'thirdparty',
})

Customizing public path example

By default, local externals are resolved from the same root path as your Webpack configuration file's output.publicPath, concatenated with the outputPath variable. This is configurable.

You should include a trailing slash in your public path, and a leading slash if you want it to resolve assets from the domain root.

This example assumes bootstrap is installed in the app. It:

copies node_modules/bootstrap/dist/css/bootstrap.min.css to <output path>/vendor/bootstrap/dist/css/bootstrap.min.css
adds <link href="/assets/vendor/bootstrap/dist/css/bootstrap.min.css" rel="stylesheet"> to your HTML file, before your chunks

new HtmlWebpackExternalsPlugin({
  externals: [
    {
      module: 'bootstrap',
      entry: 'dist/css/bootstrap.min.css',
    },
  ],
  publicPath: '/assets/',
})

Adding custom attributes to tags example

Sometimes you may want to add custom attributes to the link or script tags that are injected.

This example does not require the jquery module to be installed. It:

adds jquery to your Webpack config's externals object to exclude it from your bundle, telling it to expect a global object called jQuery (on the window object)
adds <script type="text/javascript" src="https://code.jquery.com/jquery-3.2.1.js" integrity="sha256-DZAnKJ/6XZ9si04Hgrsxu/8s717jcIzLy3oi35EouyE=" crossorigin="anonymous"></script> to your HTML file, before your chunks

new HtmlWebpackExternalsPlugin({
  externals: [
    {
      module: 'jquery',
      entry: {
        path: 'https://code.jquery.com/jquery-3.2.1.js',
        attributes: {
          integrity: 'sha256-DZAnKJ/6XZ9si04Hgrsxu/8s717jcIzLy3oi35EouyE=',
          crossorigin: 'anonymous',
        },
      },
      global: 'jQuery',
    },
  ],
})

Specifying which HTML files to affect example

If you are using multiple instances of html-webpack-plugin, by default the assets will be injected into every file. This is configurable.

This example assumes bootstrap is installed in the app. It:

copies node_modules/bootstrap/dist/css/bootstrap.min.css to <output path>/vendor/bootstrap/dist/css/bootstrap.min.css
adds <link href="/public/vendor/bootstrap/dist/css/bootstrap.min.css" rel="stylesheet"> to only the about.html file, before your chunks

new HtmlWebpackExternalsPlugin({
  externals: [
    {
      module: 'bootstrap',
      entry: 'dist/css/bootstrap.min.css',
    },
  ],
  files: ['about.html'],
})

Disabling the plugin

Sometimes you only want the plugin to be activated in certain environments. Rather than create separate Webpack configs or mess with splicing the plugins array, simply set the enabled option to false to disable the externals plugin entirely.

new HtmlWebpackExternalsPlugin({
  externals: [
    {
      module: 'jquery',
      entry: 'dist/jquery.min.js',
      global: 'jQuery',
    },
  ],
  enabled: process.env.NODE_ENV === 'production',
})

leocardoso94 / html-webpack-externals-plugin Goto Github PK