1 | [![npm][npm]][npm-url]
|
2 | [![node][node]][node-url]
|
3 | ![npm](https://img.shields.io/npm/dw/html-webpack-plugin.svg)
|
4 | [![deps][deps]][deps-url]
|
5 | [![tests][tests]][tests-url]
|
6 | [![Backers on Open Collective](https://opencollective.com/html-webpack-plugin/backers/badge.svg)](#backers)
|
7 | [![Sponsors on Open Collective](https://opencollective.com/html-webpack-plugin/sponsors/badge.svg)](#sponsors)
|
8 |
|
9 | <div align="center">
|
10 | <img width="200" height="200" src="https://worldvectorlogo.com/logos/html5.svg">
|
11 | <a href="https://github.com/webpack/webpack">
|
12 | <img width="200" height="200"
|
13 | src="https://webpack.js.org/assets/icon-square-big.svg">
|
14 | </a>
|
15 | <div>
|
16 | <img width="100" height="100" title="Webpack Plugin" src="http://michael-ciniawsky.github.io/postcss-load-plugins/logo.svg">
|
17 | </div>
|
18 | <h1>HTML Webpack Plugin</h1>
|
19 | <p>Plugin that simplifies creation of HTML files to serve your bundles</p>
|
20 | </div>
|
21 |
|
22 | <h2 align="center">Install</h2>
|
23 |
|
24 | ```bash
|
25 | npm i --save-dev html-webpack-plugin
|
26 | ```
|
27 |
|
28 | ```bash
|
29 | yarn add --dev html-webpack-plugin
|
30 | ```
|
31 |
|
32 |
|
33 | This is a [webpack](http://webpack.js.org/) plugin that simplifies creation of HTML files to serve your `webpack` bundles. This is especially useful for `webpack` bundles that include a hash in the filename which changes every compilation. You can either let the plugin generate an HTML file for you, supply
|
34 | your own template using `lodash` templates or use your own loader.
|
35 |
|
36 | <h2 align="center">Sponsors</h2>
|
37 |
|
38 | <a href="https://opencollective.com/html-webpack-plugin/sponsor/0/website" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/sponsor/0/avatar.svg"></a>
|
39 | <a href="https://opencollective.com/html-webpack-plugin/sponsor/1/website" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/sponsor/1/avatar.svg"></a>
|
40 | <a href="https://opencollective.com/html-webpack-plugin/sponsor/2/website" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/sponsor/2/avatar.svg"></a>
|
41 | <a href="https://opencollective.com/html-webpack-plugin/sponsor/3/website" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/sponsor/3/avatar.svg"></a>
|
42 | <a href="https://opencollective.com/html-webpack-plugin/sponsor/4/website" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/sponsor/4/avatar.svg"></a>
|
43 | <a href="https://opencollective.com/html-webpack-plugin/sponsor/5/website" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/sponsor/5/avatar.svg"></a>
|
44 | <a href="https://opencollective.com/html-webpack-plugin/sponsor/6/website" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/sponsor/6/avatar.svg"></a>
|
45 | <a href="https://opencollective.com/html-webpack-plugin/sponsor/7/website" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/sponsor/7/avatar.svg"></a>
|
46 | <a href="https://opencollective.com/html-webpack-plugin/sponsor/8/website" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/sponsor/8/avatar.svg"></a>
|
47 | <a href="https://opencollective.com/html-webpack-plugin/sponsor/9/website" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/sponsor/9/avatar.svg"></a>
|
48 |
|
49 | Thanks for supporting the ongoing improvements to the html-webpack-plugin!
|
50 |
|
51 | <h2 align="center">Zero Config</h2>
|
52 |
|
53 | The `html-webpack-plugin` works without configuration.
|
54 | It's a great addition to the [⚙️ webpack-config-plugins](https://github.com/namics/webpack-config-plugins/blob/master/README.md#zero-config-webpack-dev-server-example).
|
55 |
|
56 | <h2 align="center">Plugins</h2>
|
57 |
|
58 | The `html-webpack-plugin` provides [hooks](https://github.com/jantimon/html-webpack-plugin#events) to extend it to your needs. There are already some really powerful plugins which can be integrated with zero configuration
|
59 |
|
60 | * [webpack-subresource-integrity](https://www.npmjs.com/package/webpack-subresource-integrity) for enhanced asset security
|
61 | * [appcache-webpack-plugin](https://github.com/lettertwo/appcache-webpack-plugin) for iOS and Android offline usage
|
62 | * [favicons-webpack-plugin](https://github.com/jantimon/favicons-webpack-plugin) which generates favicons and icons for iOS, Android and desktop browsers
|
63 | * [html-webpack-harddisk-plugin](https://github.com/jantimon/html-webpack-harddisk-plugin) can be used to always write to disk the html file, useful when webpack-dev-server / HMR are being used
|
64 | * [html-webpack-inline-source-plugin](https://github.com/DustinJackson/html-webpack-inline-source-plugin) to inline your assets in the resulting HTML file
|
65 | * [html-webpack-inline-svg-plugin](https://github.com/thegc/html-webpack-inline-svg-plugin) to inline SVGs in the resulting HTML file.
|
66 | * [html-webpack-exclude-assets-plugin](https://github.com/jamesjieye/html-webpack-exclude-assets-plugin) for excluding assets using regular expressions
|
67 | * [html-webpack-include-assets-plugin](https://github.com/jharris4/html-webpack-include-assets-plugin) for including lists of js or css file paths (such as those copied by the copy-webpack-plugin).
|
68 | * [script-ext-html-webpack-plugin](https://github.com/numical/script-ext-html-webpack-plugin) to add `async`, `defer` or `module` attributes to your `<script>` elements, or even inline them
|
69 | * [style-ext-html-webpack-plugin](https://github.com/numical/style-ext-html-webpack-plugin) to convert your `<link>`s to external stylesheets into `<style>` elements containing internal CSS
|
70 | * [html-webpack-injector](https://github.com/thearchitgarg/html-webpack-injector) to inject chunks in `head` or `body` (different locations ) of same html document.
|
71 | * [resource-hints-webpack-plugin](https://github.com/jantimon/resource-hints-webpack-plugin) to add resource hints for faster initial page loads using `<link rel='preload'>` and `<link rel='prefetch'>`
|
72 | * [preload-webpack-plugin](https://github.com/GoogleChrome/preload-webpack-plugin) for automatically wiring up asynchronous (and other types) of JavaScript chunks using `<link rel='preload'>` helping with lazy-loading
|
73 | * [link-media-html-webpack-plugin](https://github.com/yaycmyk/link-media-html-webpack-plugin) allows for injected stylesheet `<link />` tags to have their media attribute set automatically; useful for providing specific desktop/mobile/print etc. stylesheets that the browser will conditionally download
|
74 | * [inline-chunk-manifest-html-webpack-plugin](https://github.com/jouni-kantola/inline-chunk-manifest-html-webpack-plugin) for inlining webpack's chunk manifest. Default extracts manifest and inlines in `<head>`
|
75 | * [html-webpack-inline-style-plugin](https://github.com/djaax/html-webpack-inline-style-plugin) for inlining styles to HTML elements using [juice](https://github.com/Automattic/juice). Useful for email generation automatisation.
|
76 | * [html-webpack-exclude-empty-assets-plugin](https://github.com/KnisterPeter/html-webpack-exclude-empty-assets-plugin) removes empty assets from being added to the html. This fixes some problems with extract-text-plugin with webpack 4.
|
77 | * [webpack-concat-plugin](https://github.com/hxlniada/webpack-concat-plugin) for concat and uglify files that needn't to be webpack bundles(for legacy files) and inject to html-webpack-plugin.
|
78 | * [html-webpack-link-type-plugin](https://github.com/steadyapp/html-webpack-link-type-plugin) adds a configurable mimetype to resources injected as links (such as adding type="text/css" to external stylesheets) for compatibility with "strict mode".
|
79 | * [csp-html-webpack-plugin](https://github.com/slackhq/csp-html-webpack-plugin) to add [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) meta tags to the HTML output
|
80 | * [webpack-nomodule-plugin](https://github.com/swimmadude66/webpack-nomodule-plugin) allows you to add a `nomodule` attribute to specific injected scripts, which prevents the scripts from being loaded by newer browsers. Good for limiting loads of polyfills.
|
81 | * [html-webpack-skip-assets-plugin](https://github.com/swimmadude66/html-webpack-skip-assets-plugin) Skip adding certain output files to the html file. Built as a drop-in replacement for [html-webpack-exclude-assets-plugin](https://www.npmjs.com/package/html-webpack-exclude-assets-plugin) and works with newer [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin) versions
|
82 |
|
83 |
|
84 | <h2 align="center">Usage</h2>
|
85 |
|
86 | The plugin will generate an HTML5 file for you that includes all your `webpack`
|
87 | bundles in the body using `script` tags. Just add the plugin to your `webpack`
|
88 | config as follows:
|
89 |
|
90 | **webpack.config.js**
|
91 | ```js
|
92 | const HtmlWebpackPlugin = require('html-webpack-plugin')
|
93 |
|
94 | module.exports = {
|
95 | entry: 'index.js',
|
96 | output: {
|
97 | path: __dirname + '/dist',
|
98 | filename: 'index_bundle.js'
|
99 | },
|
100 | plugins: [
|
101 | new HtmlWebpackPlugin()
|
102 | ]
|
103 | }
|
104 | ```
|
105 |
|
106 | This will generate a file `dist/index.html` containing the following
|
107 |
|
108 | ```html
|
109 | <!DOCTYPE html>
|
110 | <html>
|
111 | <head>
|
112 | <meta charset="utf-8">
|
113 | <title>Webpack App</title>
|
114 | </head>
|
115 | <body>
|
116 | <script src="index_bundle.js"></script>
|
117 | </body>
|
118 | </html>
|
119 | ```
|
120 |
|
121 | If you have multiple `webpack` entry points, they will all be included with `script` tags in the generated HTML.
|
122 |
|
123 | If you have any CSS assets in webpack's output (for example, CSS extracted with the [mini-css-extract-plugin](https://github.com/webpack-contrib/mini-css-extract-plugin))
|
124 | then these will be included with `<link>` tags in the HTML head.
|
125 |
|
126 | If you have plugins that make use of it, `html-webpack-plugin` should be ordered first before any of the integrated plugins.
|
127 |
|
128 | <h2 align="center">Options</h2>
|
129 |
|
130 | You can pass a hash of configuration options to `html-webpack-plugin`.
|
131 | Allowed values are as follows
|
132 |
|
133 | |Name|Type|Default|Description|
|
134 | |:--:|:--:|:-----:|:----------|
|
135 | |**`title`**|`{String}`|`Webpack App`|The title to use for the generated HTML document|
|
136 | |**`filename`**|`{String}`|`'index.html'`|The file to write the HTML to. Defaults to `index.html`. You can specify a subdirectory here too (eg: `assets/admin.html`)|
|
137 | |**`template`**|`{String}`|``|`webpack` relative or absolute path to the template. By default it will use `src/index.ejs` if it exists. Please see the [docs](https://github.com/jantimon/html-webpack-plugin/blob/master/docs/template-option.md) for details|
|
138 | |**`templateContent`**|`{string\|Function\|false}`|false| Can be used instead of `template` to provide an inline template - please read the [Writing Your Own Templates](https://github.com/jantimon/html-webpack-plugin#writing-your-own-templates) section |
|
139 | |**`templateParameters`**|`{Boolean\|Object\|Function}`| `false`| Allows to overwrite the parameters used in the template - see [example](https://github.com/jantimon/html-webpack-plugin/tree/master/examples/template-parameters) |
|
140 | |**`inject`**|`{Boolean\|String}`|`true`|`true \|\| 'head' \|\| 'body' \|\| false` Inject all assets into the given `template` or `templateContent`. When passing `true` or `'body'` all javascript resources will be placed at the bottom of the body element. `'head'` will place the scripts in the head element - see the [inject:false example](https://github.com/jantimon/html-webpack-plugin/tree/master/examples/custom-insertion-position)|
|
141 | |**`publicPath`**|`{String|'auto'}`|`'auto'`|The publicPath used for script and link tags|
|
142 | |**`scriptLoading`**|`{'blocking'\|'defer'}`|`'blocking'`| Modern browsers support non blocking javascript loading (`'defer'`) to improve the page startup performance. |
|
143 | |**`favicon`**|`{String}`|``|Adds the given favicon path to the output HTML|
|
144 | |**`meta`**|`{Object}`|`{}`|Allows to inject `meta`-tags. E.g. `meta: {viewport: 'width=device-width, initial-scale=1, shrink-to-fit=no'}`|
|
145 | |**`base`**|`{Object\|String\|false}`|`false`|Inject a [`base`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/base) tag. E.g. `base: "https://example.com/path/page.html`|
|
146 | |**`minify`**|`{Boolean\|Object}`|`true` if `mode` is `'production'`, otherwise `false`|Controls if and in what ways the output should be minified. See [minification](#minification) below for more details.|
|
147 | |**`hash`**|`{Boolean}`|`false`|If `true` then append a unique `webpack` compilation hash to all included scripts and CSS files. This is useful for cache busting|
|
148 | |**`cache`**|`{Boolean}`|`true`|Emit the file only if it was changed|
|
149 | |**`showErrors`**|`{Boolean}`|`true`|Errors details will be written into the HTML page|
|
150 | |**`chunks`**|`{?}`|`?`|Allows you to add only some chunks (e.g only the unit-test chunk)|
|
151 | |**`chunksSortMode`**|`{String\|Function}`|`auto`|Allows to control how chunks should be sorted before they are included to the HTML. Allowed values are `'none' \| 'auto' \| 'manual' \| {Function}`|
|
152 | |**`excludeChunks`**|`{Array.<string>}`|``|Allows you to skip some chunks (e.g don't add the unit-test chunk)|
|
153 | |**`xhtml`**|`{Boolean}`|`false`|If `true` render the `link` tags as self-closing (XHTML compliant)|
|
154 |
|
155 | Here's an example webpack config illustrating how to use these options
|
156 |
|
157 | **webpack.config.js**
|
158 | ```js
|
159 | {
|
160 | entry: 'index.js',
|
161 | output: {
|
162 | path: __dirname + '/dist',
|
163 | filename: 'index_bundle.js'
|
164 | },
|
165 | plugins: [
|
166 | new HtmlWebpackPlugin({
|
167 | title: 'My App',
|
168 | filename: 'assets/admin.html'
|
169 | })
|
170 | ]
|
171 | }
|
172 | ```
|
173 |
|
174 | ### Generating Multiple HTML Files
|
175 |
|
176 | To generate more than one HTML file, declare the plugin more than
|
177 | once in your plugins array
|
178 |
|
179 | **webpack.config.js**
|
180 | ```js
|
181 | {
|
182 | entry: 'index.js',
|
183 | output: {
|
184 | path: __dirname + '/dist',
|
185 | filename: 'index_bundle.js'
|
186 | },
|
187 | plugins: [
|
188 | new HtmlWebpackPlugin(), // Generates default index.html
|
189 | new HtmlWebpackPlugin({ // Also generate a test.html
|
190 | filename: 'test.html',
|
191 | template: 'src/assets/test.html'
|
192 | })
|
193 | ]
|
194 | }
|
195 | ```
|
196 |
|
197 | ### Writing Your Own Templates
|
198 |
|
199 | If the default generated HTML doesn't meet your needs you can supply
|
200 | your own template. The easiest way is to use the `template` option and pass a custom HTML file.
|
201 | The html-webpack-plugin will automatically inject all necessary CSS, JS, manifest
|
202 | and favicon files into the markup.
|
203 |
|
204 | Details of other template loaders are [documented here](https://github.com/jantimon/html-webpack-plugin/blob/master/docs/template-option.md).
|
205 |
|
206 | ```js
|
207 | plugins: [
|
208 | new HtmlWebpackPlugin({
|
209 | title: 'Custom template',
|
210 | // Load a custom template (lodash by default)
|
211 | template: 'index.html'
|
212 | })
|
213 | ]
|
214 | ```
|
215 |
|
216 | **index.html**
|
217 | ```html
|
218 | <!DOCTYPE html>
|
219 | <html>
|
220 | <head>
|
221 | <meta charset="utf-8"/>
|
222 | <title><%= htmlWebpackPlugin.options.title %></title>
|
223 | </head>
|
224 | <body>
|
225 | </body>
|
226 | </html>
|
227 | ```
|
228 |
|
229 | If you already have a template loader, you can use it to parse the template.
|
230 | Please note that this will also happen if you specify the html-loader and use `.html` file as template.
|
231 |
|
232 | **webpack.config.js**
|
233 | ```js
|
234 | module: {
|
235 | loaders: [
|
236 | { test: /\.hbs$/, loader: "handlebars-loader" }
|
237 | ]
|
238 | },
|
239 | plugins: [
|
240 | new HtmlWebpackPlugin({
|
241 | title: 'Custom template using Handlebars',
|
242 | template: 'index.hbs'
|
243 | })
|
244 | ]
|
245 | ```
|
246 |
|
247 | You can use the `lodash` syntax out of the box. If the `inject` feature doesn't fit your needs and you want full control over the asset placement use the [default template](https://github.com/jaketrent/html-webpack-template/blob/86f285d5c790a6c15263f5cc50fd666d51f974fd/index.html) of the [html-webpack-template project](https://github.com/jaketrent/html-webpack-template) as a starting point for writing your own.
|
248 |
|
249 | The following variables are available in the template by default (you can extend them using the `templateParameters` option):
|
250 |
|
251 | - `htmlWebpackPlugin`: data specific to this plugin
|
252 |
|
253 | - `htmlWebpackPlugin.options`: the options hash that was passed to
|
254 | the plugin. In addition to the options actually used by this plugin,
|
255 | you can use this hash to pass arbitrary data through to your template.
|
256 |
|
257 | - `htmlWebpackPlugin.tags`: the prepared `headTags` and `bodyTags` Array to render the `<base>`, `<meta>`, `<script>` and `<link>` tags.
|
258 | Can be used directly in templates and literals. For example:
|
259 | ```html
|
260 | <html>
|
261 | <head>
|
262 | <%= htmlWebpackPlugin.tags.headTags %>
|
263 | </head>
|
264 | <body>
|
265 | <%= htmlWebpackPlugin.tags.bodyTags %>
|
266 | </body>
|
267 | </html>
|
268 | ```
|
269 |
|
270 | - `htmlWebpackPlugin.files`: direct access to the files used during the compilation.
|
271 |
|
272 | ```typescript
|
273 | publicPath: string;
|
274 | js: string[];
|
275 | css: string[];
|
276 | manifest?: string;
|
277 | favicon?: string;
|
278 | ```
|
279 |
|
280 |
|
281 | - `webpackConfig`: the webpack configuration that was used for this compilation. This
|
282 | can be used, for example, to get the `publicPath` (`webpackConfig.output.publicPath`).
|
283 |
|
284 | - `compilation`: the webpack [compilation object](https://webpack.js.org/api/compilation-object/).
|
285 | This can be used, for example, to get the contents of processed assets and inline them
|
286 | directly in the page, through `compilation.assets[...].source()`
|
287 | (see [the inline template example](examples/inline/template.pug)).
|
288 |
|
289 |
|
290 | The template can also be directly inlined directly into the options object.
|
291 | ⚠️ **`templateContent` does not allow to use webpack loaders for your template and will not watch for template file changes**
|
292 |
|
293 | **webpack.config.js**
|
294 | ```js
|
295 | new HtmlWebpackPlugin({
|
296 | templateContent: `
|
297 | <html>
|
298 | <body>
|
299 | <h1>Hello World</h1>
|
300 | </body>
|
301 | </html>
|
302 | `
|
303 | })
|
304 | ```
|
305 |
|
306 | The `templateContent` can also access all `templateParameters` values.
|
307 | ⚠️ **`templateContent` does not allow to use webpack loaders for your template and will not watch for template file changes**
|
308 |
|
309 | **webpack.config.js**
|
310 | ```js
|
311 | new HtmlWebpackPlugin({
|
312 | inject: false,
|
313 | templateContent: ({htmlWebpackPlugin}) => `
|
314 | <html>
|
315 | <head>
|
316 | ${htmlWebpackPlugin.tags.headTags}
|
317 | </head>
|
318 | <body>
|
319 | <h1>Hello World</h1>
|
320 | ${htmlWebpackPlugin.tags.bodyTags}
|
321 | </body>
|
322 | </html>
|
323 | `
|
324 | })
|
325 | ```
|
326 |
|
327 | ### Filtering Chunks
|
328 |
|
329 | To include only certain chunks you can limit the chunks being used
|
330 |
|
331 | **webpack.config.js**
|
332 | ```js
|
333 | plugins: [
|
334 | new HtmlWebpackPlugin({
|
335 | chunks: ['app']
|
336 | })
|
337 | ]
|
338 | ```
|
339 |
|
340 | It is also possible to exclude certain chunks by setting the `excludeChunks` option
|
341 |
|
342 | **webpack.config.js**
|
343 | ```js
|
344 | plugins: [
|
345 | new HtmlWebpackPlugin({
|
346 | excludeChunks: [ 'dev-helper' ]
|
347 | })
|
348 | ]
|
349 | ```
|
350 |
|
351 | ### Minification
|
352 |
|
353 | If the `minify` option is set to `true` (the default when webpack's `mode` is `'production'`),
|
354 | the generated HTML will be minified using [html-minifier-terser](https://github.com/DanielRuf/html-minifier-terser)
|
355 | and the following options:
|
356 |
|
357 | ```js
|
358 | {
|
359 | collapseWhitespace: true,
|
360 | removeComments: true,
|
361 | removeRedundantAttributes: true,
|
362 | removeScriptTypeAttributes: true,
|
363 | removeStyleLinkTypeAttributes: true,
|
364 | useShortDoctype: true
|
365 | }
|
366 | ```
|
367 |
|
368 | To use custom [html-minifier options](https://github.com/DanielRuf/html-minifier-terser#options-quick-reference)
|
369 | pass an object to `minify` instead. This object will not be merged with the defaults above.
|
370 |
|
371 | To disable minification during production mode set the `minify` option to `false`.
|
372 |
|
373 | ### Meta Tags
|
374 |
|
375 | If the `meta` option is set the html-webpack-plugin will inject meta tags.
|
376 | For the default template the html-webpack-plugin will already provide a default for the `viewport` meta tag.
|
377 |
|
378 | Please take a look at this well maintained list of almost all [possible meta tags](https://github.com/joshbuchea/HEAD#meta).
|
379 |
|
380 | #### name/content meta tags
|
381 |
|
382 | Most meta tags are configured by setting a `name` and a `content` attribute.
|
383 | To add those use a key/value pair:
|
384 |
|
385 | **webpack.config.js**
|
386 | ```js
|
387 | plugins: [
|
388 | new HtmlWebpackPlugin({
|
389 | 'meta': {
|
390 | 'viewport': 'width=device-width, initial-scale=1, shrink-to-fit=no',
|
391 | // Will generate: <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
|
392 | 'theme-color': '#4285f4'
|
393 | // Will generate: <meta name="theme-color" content="#4285f4">
|
394 | }
|
395 | })
|
396 | ]
|
397 | ```
|
398 |
|
399 | #### Simulate http response headers
|
400 |
|
401 | The **http-equiv** attribute is essentially used to simulate a HTTP response header.
|
402 | This format is supported using an object notation which allows you to add any attribute:
|
403 |
|
404 | **webpack.config.js**
|
405 | ```js
|
406 | plugins: [
|
407 | new HtmlWebpackPlugin({
|
408 | 'meta': {
|
409 | 'Content-Security-Policy': { 'http-equiv': 'Content-Security-Policy', 'content': 'default-src https:' },
|
410 | // Will generate: <meta http-equiv="Content-Security-Policy" content="default-src https:">
|
411 | // Which equals to the following http header: `Content-Security-Policy: default-src https:`
|
412 | 'set-cookie': { 'http-equiv': 'set-cookie', content: 'name=value; expires=date; path=url' },
|
413 | // Will generate: <meta http-equiv="set-cookie" content="value; expires=date; path=url">
|
414 | // Which equals to the following http header: `set-cookie: value; expires=date; path=url`
|
415 | }
|
416 | })
|
417 | ]
|
418 | ```
|
419 |
|
420 | ### Base Tag
|
421 |
|
422 | When the `base` option is used,
|
423 | html-webpack-plugin will inject a [base tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/base).
|
424 | By default, a base tag will not be injected.
|
425 |
|
426 | The following two are identical and will both insert `<base href="http://example.com/some/page.html">`:
|
427 |
|
428 | ```js
|
429 | new HtmlWebpackPlugin({
|
430 | 'base': 'http://example.com/some/page.html'
|
431 | })
|
432 | ```
|
433 |
|
434 | ```js
|
435 | new HtmlWebpackPlugin({
|
436 | 'base': { 'href': 'http://example.com/some/page.html' }
|
437 | })
|
438 | ```
|
439 |
|
440 | The `target` can be specified with the corresponding key:
|
441 |
|
442 | ```js
|
443 | new HtmlWebpackPlugin({
|
444 | 'base': {
|
445 | 'href': 'http://example.com/some/page.html',
|
446 | 'target': '_blank'
|
447 | }
|
448 | })
|
449 | ```
|
450 |
|
451 | which will inject the element `<base href="http://example.com/some/page.html" target="_blank">`.
|
452 |
|
453 | ### Long Term Caching
|
454 |
|
455 | For long term caching add `contenthash/templatehash` to the filename.
|
456 |
|
457 | **Example:**
|
458 |
|
459 | ```js
|
460 | plugins: [
|
461 | new HtmlWebpackPlugin({
|
462 | filename: 'index.[contenthash].html'
|
463 | })
|
464 | ]
|
465 | ```
|
466 |
|
467 | `contenthash/templatehash` is the hash of the content of the output file.
|
468 |
|
469 | Optionally, You can configure like `[<hashType>:contenthash:<digestType>:<length>]`
|
470 |
|
471 | * `hashType` - one of `sha1`, `md5`, `sha256`, `sha512` or any other node.js supported hash type
|
472 | * `digestType` - one of `hex`, `base26`, `base32`, `base36`, `base49`, `base52`, `base58`, `base62`, `base64`
|
473 | * `maxlength` - maximum length of the generated hash in chars
|
474 |
|
475 | **Defaults:** `[md5:contenthash:hex:9999]`
|
476 |
|
477 | ### Events
|
478 |
|
479 | To allow other [plugins](https://github.com/webpack/docs/wiki/plugins) to alter the HTML this plugin executes
|
480 | [tapable](https://github.com/webpack/tapable/tree/master) hooks.
|
481 |
|
482 | The [lib/hooks.js](https://github.com/jantimon/html-webpack-plugin/blob/master/lib/hooks.js) contains all information
|
483 | about which values are passed.
|
484 |
|
485 | [![Concept flow uml](https://raw.githubusercontent.com/jantimon/html-webpack-plugin/master/flow.png)](https://github.com/jantimon/html-webpack-plugin/blob/master/flow.puml)
|
486 |
|
487 | #### `beforeAssetTagGeneration` hook
|
488 |
|
489 | ```
|
490 | AsyncSeriesWaterfallHook<{
|
491 | assets: {
|
492 | publicPath: string,
|
493 | js: Array<{string}>,
|
494 | css: Array<{string}>,
|
495 | favicon?: string | undefined,
|
496 | manifest?: string | undefined
|
497 | },
|
498 | outputName: string,
|
499 | plugin: HtmlWebpackPlugin
|
500 | }>
|
501 | ```
|
502 |
|
503 | #### `alterAssetTags` hook
|
504 |
|
505 | ```
|
506 | AsyncSeriesWaterfallHook<{
|
507 | assetTags: {
|
508 | scripts: Array<HtmlTagObject>,
|
509 | styles: Array<HtmlTagObject>,
|
510 | meta: Array<HtmlTagObject>,
|
511 | },
|
512 | outputName: string,
|
513 | plugin: HtmlWebpackPlugin
|
514 | }>
|
515 | ```
|
516 |
|
517 | #### `alterAssetTagGroups` hook
|
518 |
|
519 | ```
|
520 | AsyncSeriesWaterfallHook<{
|
521 | headTags: Array<HtmlTagObject | HtmlTagObject>,
|
522 | bodyTags: Array<HtmlTagObject | HtmlTagObject>,
|
523 | outputName: string,
|
524 | plugin: HtmlWebpackPlugin
|
525 | }>
|
526 | ```
|
527 |
|
528 | #### `afterTemplateExecution` hook
|
529 |
|
530 | ```
|
531 | AsyncSeriesWaterfallHook<{
|
532 | html: string,
|
533 | headTags: Array<HtmlTagObject | HtmlTagObject>,
|
534 | bodyTags: Array<HtmlTagObject | HtmlTagObject>,
|
535 | outputName: string,
|
536 | plugin: HtmlWebpackPlugin,
|
537 | }>
|
538 | ```
|
539 |
|
540 | #### `beforeEmit` hook
|
541 |
|
542 | ```
|
543 | AsyncSeriesWaterfallHook<{
|
544 | html: string,
|
545 | outputName: string,
|
546 | plugin: HtmlWebpackPlugin,
|
547 | }>
|
548 | ```
|
549 |
|
550 | #### `afterEmit` hook
|
551 |
|
552 | ```
|
553 | AsyncSeriesWaterfallHook<{
|
554 | outputName: string,
|
555 | plugin: HtmlWebpackPlugin
|
556 | }>
|
557 | ```
|
558 |
|
559 | Example implementation: [webpack-subresource-integrity](https://www.npmjs.com/package/webpack-subresource-integrity)
|
560 |
|
561 | **plugin.js**
|
562 | ```js
|
563 | // If your plugin is direct dependent to the html webpack plugin:
|
564 | const HtmlWebpackPlugin = require('html-webpack-plugin');
|
565 | // If your plugin is using html-webpack-plugin as an optional dependency
|
566 | // you can use https://github.com/tallesl/node-safe-require instead:
|
567 | const HtmlWebpackPlugin = require('safe-require')('html-webpack-plugin');
|
568 |
|
569 | class MyPlugin {
|
570 | apply (compiler) {
|
571 | compiler.hooks.compilation.tap('MyPlugin', (compilation) => {
|
572 | console.log('The compiler is starting a new compilation...')
|
573 |
|
574 | // Static Plugin interface |compilation |HOOK NAME | register listener
|
575 | HtmlWebpackPlugin.getHooks(compilation).beforeEmit.tapAsync(
|
576 | 'MyPlugin', // <-- Set a meaningful name here for stacktraces
|
577 | (data, cb) => {
|
578 | // Manipulate the content
|
579 | data.html += 'The Magic Footer'
|
580 | // Tell webpack to move on
|
581 | cb(null, data)
|
582 | }
|
583 | )
|
584 | })
|
585 | }
|
586 | }
|
587 |
|
588 | module.exports = MyPlugin
|
589 | ```
|
590 |
|
591 | **webpack.config.js**
|
592 | ```js
|
593 | plugins: [
|
594 | new MyPlugin({ options: '' })
|
595 | ]
|
596 | ```
|
597 |
|
598 | Note that the callback must be passed the HtmlWebpackPluginData in order to pass this onto any other plugins listening on the same `beforeEmit` event
|
599 |
|
600 | <h2 align="center">Maintainers</h2>
|
601 |
|
602 | <table>
|
603 | <tbody>
|
604 | <tr>
|
605 | <td align="center">
|
606 | <img width="150" height="150"
|
607 | src="https://avatars3.githubusercontent.com/u/4113649?v=3&s=150">
|
608 | </br>
|
609 | <a href="https://github.com/jantimon">Jan Nicklas</a>
|
610 | </td>
|
611 | <td align="center">
|
612 | <img width="150" height="150"
|
613 | src="https://avatars2.githubusercontent.com/u/4112409?v=3&s=150">
|
614 | </br>
|
615 | <a href="https://github.com/mastilver">Thomas Sileghem</a>
|
616 | </td>
|
617 | </tr>
|
618 | <tbody>
|
619 | </table>
|
620 |
|
621 |
|
622 | ## Backers
|
623 |
|
624 | Thank you to all our backers!
|
625 | If you want to support the project as well [become a sponsor](https://opencollective.com/html-webpack-plugin#sponsor) or a [a backer](https://opencollective.com/html-webpack-plugin#backer).
|
626 |
|
627 | <a href="https://opencollective.com/html-webpack-plugin/backer/0/website?requireActive=false" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/backer/0/avatar.svg?requireActive=false"></a>
|
628 | <a href="https://opencollective.com/html-webpack-plugin/backer/1/website?requireActive=false" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/backer/1/avatar.svg?requireActive=false"></a>
|
629 | <a href="https://opencollective.com/html-webpack-plugin/backer/2/website?requireActive=false" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/backer/2/avatar.svg?requireActive=false"></a>
|
630 | <a href="https://opencollective.com/html-webpack-plugin/backer/3/website?requireActive=false" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/backer/3/avatar.svg?requireActive=false"></a>
|
631 | <a href="https://opencollective.com/html-webpack-plugin/backer/4/website?requireActive=false" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/backer/4/avatar.svg?requireActive=false"></a>
|
632 | <a href="https://opencollective.com/html-webpack-plugin/backer/5/website?requireActive=false" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/backer/5/avatar.svg?requireActive=false"></a>
|
633 | <a href="https://opencollective.com/html-webpack-plugin/backer/6/website?requireActive=false" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/backer/6/avatar.svg?requireActive=false"></a>
|
634 | <a href="https://opencollective.com/html-webpack-plugin/backer/7/website?requireActive=false" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/backer/7/avatar.svg?requireActive=false"></a>
|
635 | <a href="https://opencollective.com/html-webpack-plugin/backer/8/website?requireActive=false" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/backer/8/avatar.svg?requireActive=false"></a>
|
636 | <a href="https://opencollective.com/html-webpack-plugin/backer/9/website?requireActive=false" target="_blank"><img src="https://opencollective.com/html-webpack-plugin/backer/9/avatar.svg?requireActive=false"></a>
|
637 |
|
638 |
|
639 | ## Contributors
|
640 |
|
641 | This project exists thanks to all the people who contribute.
|
642 |
|
643 | You're free to contribute to this project by submitting [issues](https://github.com/jantimon/html-webpack-plugin/issues) and/or [pull requests](https://github.com/jantimon/html-webpack-plugin/pulls). This project is test-driven, so keep in mind that every change and new feature should be covered by tests.
|
644 |
|
645 | This project uses the [semistandard code style](https://github.com/Flet/semistandard).
|
646 |
|
647 | <a href="https://github.com/jantimon/html-webpack-plugin/graphs/contributors"><img src="https://opencollective.com/html-webpack-plugin/contributors.svg?width=890&button=false" /></a>
|
648 |
|
649 |
|
650 | [npm]: https://img.shields.io/npm/v/html-webpack-plugin.svg
|
651 | [npm-url]: https://npmjs.com/package/html-webpack-plugin
|
652 |
|
653 | [node]: https://img.shields.io/node/v/html-webpack-plugin.svg
|
654 | [node-url]: https://nodejs.org
|
655 |
|
656 | [deps]: https://david-dm.org/jantimon/html-webpack-plugin.svg
|
657 | [deps-url]: https://david-dm.org/jantimon/html-webpack-plugin
|
658 |
|
659 | [tests]: http://img.shields.io/travis/jantimon/html-webpack-plugin.svg
|
660 | [tests-url]: https://travis-ci.org/jantimon/html-webpack-plugin
|