1 | HTML Webpack Plugin
|
2 | ===================
|
3 | [![npm version](https://badge.fury.io/js/html-webpack-plugin.svg)](http://badge.fury.io/js/html-webpack-plugin) [![Dependency Status](https://david-dm.org/ampedandwired/html-webpack-plugin.svg)](https://david-dm.org/ampedandwired/html-webpack-plugin) [![Build status](https://travis-ci.org/ampedandwired/html-webpack-plugin.svg)](https://travis-ci.org/ampedandwired/html-webpack-plugin) [![Windows build status](https://ci.appveyor.com/api/projects/status/github/ampedandwired/html-webpack-plugin?svg=true&branch=master)](https://ci.appveyor.com/project/jantimon/html-webpack-plugin) [![js-semistandard-style](https://img.shields.io/badge/code%20style-semistandard-brightgreen.svg?style=flat-square)](https://github.com/Flet/semistandard) [![bitHound Dependencies](https://www.bithound.io/github/ampedandwired/html-webpack-plugin/badges/dependencies.svg)](https://www.bithound.io/github/ampedandwired/html-webpack-plugin/master/dependencies/npm) [![license](https://img.shields.io/github/license/mashape/apistatus.svg?maxAge=2592000)]()
|
4 |
|
5 | [![NPM](https://nodei.co/npm/html-webpack-plugin.png?downloads=true&downloadRank=true&stars=true)](https://nodei.co/npm/html-webpack-plugin/)
|
6 |
|
7 | This is a [webpack](http://webpack.github.io/) plugin that simplifies creation of HTML files to serve your
|
8 | webpack bundles. This is especially useful for webpack bundles that include
|
9 | a hash in the filename which changes every compilation. You can either let the plugin generate an HTML file for you, supply
|
10 | your own template using lodash templates or use your own loader.
|
11 |
|
12 | Maintainer: Jan Nicklas [@jantimon](https://twitter.com/jantimon)
|
13 |
|
14 | Installation
|
15 | ------------
|
16 | Install the plugin with npm:
|
17 | ```shell
|
18 | $ npm install html-webpack-plugin --save-dev
|
19 | ```
|
20 |
|
21 | Migration guide from 1.x
|
22 | ------------------------
|
23 |
|
24 | [Changelog](https://github.com/ampedandwired/html-webpack-plugin/blob/master/CHANGELOG.md)
|
25 |
|
26 | If you used the 1.x version please take a look at the [migration guide](https://github.com/ampedandwired/html-webpack-plugin/blob/master/migration.md)
|
27 |
|
28 |
|
29 | Basic Usage
|
30 | -----------
|
31 |
|
32 | The plugin will generate an HTML5 file for you that includes all your webpack
|
33 | bundles in the body using `script` tags. Just add the plugin to your webpack
|
34 | config as follows:
|
35 |
|
36 | ```javascript
|
37 | var HtmlWebpackPlugin = require('html-webpack-plugin');
|
38 | var webpackConfig = {
|
39 | entry: 'index.js',
|
40 | output: {
|
41 | path: 'dist',
|
42 | filename: 'index_bundle.js'
|
43 | },
|
44 | plugins: [new HtmlWebpackPlugin()]
|
45 | };
|
46 | ```
|
47 |
|
48 | This will generate a file `dist/index.html` containing the following:
|
49 | ```html
|
50 | <!DOCTYPE html>
|
51 | <html>
|
52 | <head>
|
53 | <meta charset="UTF-8">
|
54 | <title>Webpack App</title>
|
55 | </head>
|
56 | <body>
|
57 | <script src="index_bundle.js"></script>
|
58 | </body>
|
59 | </html>
|
60 | ```
|
61 |
|
62 | If you have multiple webpack entry points, they will all be included with `script`
|
63 | tags in the generated HTML.
|
64 |
|
65 | If you have any CSS assets in webpack's output (for example, CSS extracted
|
66 | with the [ExtractTextPlugin](https://github.com/webpack/extract-text-webpack-plugin))
|
67 | then these will be included with `<link>` tags in the HTML head.
|
68 |
|
69 | Configuration
|
70 | -------------
|
71 | You can pass a hash of configuration options to `HtmlWebpackPlugin`.
|
72 | Allowed values are as follows:
|
73 |
|
74 | - `title`: The title to use for the generated HTML document.
|
75 | - `filename`: The file to write the HTML to. Defaults to `index.html`.
|
76 | You can specify a subdirectory here too (eg: `assets/admin.html`).
|
77 | - `template`: Webpack require path to the template. Please see the [docs](https://github.com/ampedandwired/html-webpack-plugin/blob/master/docs/template-option.md) for details.
|
78 | - `inject`: `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.
|
79 | - `favicon`: Adds the given favicon path to the output html.
|
80 | - `minify`: `{...} | false` Pass a [html-minifier](https://github.com/kangax/html-minifier#options-quick-reference) options object to minify the output.
|
81 | - `hash`: `true | false` if `true` then append a unique webpack compilation hash to all
|
82 | included scripts and CSS files. This is useful for cache busting.
|
83 | - `cache`: `true | false` if `true` (default) try to emit the file only if it was changed.
|
84 | - `showErrors`: `true | false` if `true` (default) errors details will be written into the html page.
|
85 | - `chunks`: Allows you to add only some chunks (e.g. only the unit-test chunk)
|
86 | - `chunksSortMode`: Allows to control how chunks should be sorted before they are included to the html. Allowed values: 'none' | 'auto' | 'dependency' | {function} - default: 'auto'
|
87 | - `excludeChunks`: Allows you to skip some chunks (e.g. don't add the unit-test chunk)
|
88 | - `xhtml`: `true | false` If `true` render the `link` tags as self-closing, XHTML compliant. Default is `false`
|
89 |
|
90 | Here's an example webpack config illustrating how to use these options:
|
91 | ```javascript
|
92 | {
|
93 | entry: 'index.js',
|
94 | output: {
|
95 | path: 'dist',
|
96 | filename: 'index_bundle.js'
|
97 | },
|
98 | plugins: [
|
99 | new HtmlWebpackPlugin({
|
100 | title: 'My App',
|
101 | filename: 'assets/admin.html'
|
102 | })
|
103 | ]
|
104 | }
|
105 | ```
|
106 |
|
107 | FAQ
|
108 | ----
|
109 |
|
110 | * [Why is my html minified?](https://github.com/ampedandwired/html-webpack-plugin/blob/master/docs/template-option.md)
|
111 | * [Why is my `<% ... %>` template not working?](https://github.com/ampedandwired/html-webpack-plugin/blob/master/docs/template-option.md)
|
112 | * [How can I use handlebars/pug/ejs as template engine](https://github.com/ampedandwired/html-webpack-plugin/blob/master/docs/template-option.md)
|
113 |
|
114 | Generating Multiple HTML Files
|
115 | ------------------------------
|
116 | To generate more than one HTML file, declare the plugin more than
|
117 | once in your plugins array:
|
118 | ```javascript
|
119 | {
|
120 | entry: 'index.js',
|
121 | output: {
|
122 | path: 'dist',
|
123 | filename: 'index_bundle.js'
|
124 | },
|
125 | plugins: [
|
126 | new HtmlWebpackPlugin(), // Generates default index.html
|
127 | new HtmlWebpackPlugin({ // Also generate a test.html
|
128 | filename: 'test.html',
|
129 | template: 'src/assets/test.html'
|
130 | })
|
131 | ]
|
132 | }
|
133 | ```
|
134 |
|
135 | Writing Your Own Templates
|
136 | --------------------------
|
137 | If the default generated HTML doesn't meet your needs you can supply
|
138 | your own template. The easiest way is to use the `template` option and pass a custom html file.
|
139 | The html-webpack-plugin will automatically inject all necessary CSS, JS, manifest
|
140 | and favicon files into the markup.
|
141 |
|
142 | ```javascript
|
143 | plugins: [
|
144 | new HtmlWebpackPlugin({
|
145 | title: 'Custom template',
|
146 | template: 'my-index.ejs', // Load a custom template (ejs by default see the FAQ for details)
|
147 | })
|
148 | ]
|
149 | ```
|
150 |
|
151 | `my-index.ejs`:
|
152 |
|
153 | ```html
|
154 | <!DOCTYPE html>
|
155 | <html>
|
156 | <head>
|
157 | <meta http-equiv="Content-type" content="text/html; charset=utf-8"/>
|
158 | <title><%= htmlWebpackPlugin.options.title %></title>
|
159 | </head>
|
160 | <body>
|
161 | </body>
|
162 | </html>
|
163 | ```
|
164 |
|
165 | If you already have a template loader, you can use it to parse the template.
|
166 | Please note that this will also happen if you specifiy the html-loader and use `.html` file as template.
|
167 |
|
168 | ```javascript
|
169 | module: {
|
170 | loaders: [
|
171 | { test: /\.hbs$/, loader: "handlebars" }
|
172 | ]
|
173 | },
|
174 | plugins: [
|
175 | new HtmlWebpackPlugin({
|
176 | title: 'Custom template using Handlebars',
|
177 | template: 'my-index.hbs'
|
178 | })
|
179 | ]
|
180 | ```
|
181 |
|
182 | You can use the lodash syntax out of the box.
|
183 | 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.
|
184 |
|
185 | The following variables are available in the template:
|
186 | - `htmlWebpackPlugin`: data specific to this plugin
|
187 | - `htmlWebpackPlugin.files`: a massaged representation of the
|
188 | `assetsByChunkName` attribute of webpack's [stats](https://github.com/webpack/docs/wiki/node.js-api#stats)
|
189 | object. It contains a mapping from entry point name to the bundle filename, eg:
|
190 | ```json
|
191 | "htmlWebpackPlugin": {
|
192 | "files": {
|
193 | "css": [ "main.css" ],
|
194 | "js": [ "assets/head_bundle.js", "assets/main_bundle.js"],
|
195 | "chunks": {
|
196 | "head": {
|
197 | "entry": "assets/head_bundle.js",
|
198 | "css": [ "main.css" ]
|
199 | },
|
200 | "main": {
|
201 | "entry": "assets/main_bundle.js",
|
202 | "css": []
|
203 | },
|
204 | }
|
205 | }
|
206 | }
|
207 | ```
|
208 | If you've set a publicPath in your webpack config this will be reflected
|
209 | correctly in this assets hash.
|
210 |
|
211 | - `htmlWebpackPlugin.options`: the options hash that was passed to
|
212 | the plugin. In addition to the options actually used by this plugin,
|
213 | you can use this hash to pass arbitrary data through to your template.
|
214 |
|
215 | - `webpack`: the webpack [stats](https://github.com/webpack/docs/wiki/node.js-api#stats)
|
216 | object. Note that this is the stats object as it was at the time the HTML template
|
217 | was emitted and as such may not have the full set of stats that are available
|
218 | after the wepback run is complete.
|
219 |
|
220 | - `webpackConfig`: the webpack configuration that was used for this compilation. This
|
221 | can be used, for example, to get the `publicPath` (`webpackConfig.output.publicPath`).
|
222 |
|
223 |
|
224 | Filtering chunks
|
225 | ----------------
|
226 |
|
227 | To include only certain chunks you can limit the chunks being used:
|
228 |
|
229 | ```javascript
|
230 | plugins: [
|
231 | new HtmlWebpackPlugin({
|
232 | chunks: ['app']
|
233 | })
|
234 | ]
|
235 | ```
|
236 |
|
237 | It is also possible to exclude certain chunks by setting the `excludeChunks` option:
|
238 |
|
239 | ```javascript
|
240 | plugins: [
|
241 | new HtmlWebpackPlugin({
|
242 | excludeChunks: ['dev-helper']
|
243 | })
|
244 | ]
|
245 | ```
|
246 |
|
247 | Events
|
248 | ------
|
249 |
|
250 | To allow other [plugins](https://github.com/webpack/docs/wiki/plugins) to alter the html this plugin executes the following events:
|
251 |
|
252 | Async:
|
253 |
|
254 | * `html-webpack-plugin-before-html-generation`
|
255 | * `html-webpack-plugin-before-html-processing`
|
256 | * `html-webpack-plugin-alter-asset-tags`
|
257 | * `html-webpack-plugin-after-html-processing`
|
258 | * `html-webpack-plugin-after-emit`
|
259 |
|
260 | Sync:
|
261 |
|
262 | * `html-webpack-plugin-alter-chunks`
|
263 |
|
264 | Example implementation: [html-webpack-harddisk-plugin](https://github.com/jantimon/html-webpack-harddisk-plugin)
|
265 |
|
266 | Usage:
|
267 |
|
268 | ```javascript
|
269 | // MyPlugin.js
|
270 |
|
271 | function MyPlugin(options) {
|
272 | // Configure your plugin with options...
|
273 | }
|
274 |
|
275 | MyPlugin.prototype.apply = function(compiler) {
|
276 | // ...
|
277 | compiler.plugin('compilation', function(compilation) {
|
278 | console.log('The compiler is starting a new compilation...');
|
279 |
|
280 | compilation.plugin('html-webpack-plugin-before-html-processing', function(htmlPluginData, callback) {
|
281 | htmlPluginData.html += 'The magic footer';
|
282 | callback(null, htmlPluginData);
|
283 | });
|
284 | });
|
285 |
|
286 | };
|
287 |
|
288 | module.exports = MyPlugin;
|
289 | ```
|
290 | Then in `webpack.config.js`
|
291 |
|
292 | ```javascript
|
293 | plugins: [
|
294 | new MyPlugin({options: ''})
|
295 | ]
|
296 | ```
|
297 |
|
298 | Note that the callback must be passed the htmlPluginData in order to pass this onto any other plugins listening on the same 'html-webpack-plugin-before-html-processing' event.
|
299 |
|
300 |
|
301 | # Contribution
|
302 |
|
303 | You're free to contribute to this project by submitting [issues](https://github.com/ampedandwired/html-webpack-plugin/issues) and/or [pull requests](https://github.com/ampedandwired/html-webpack-plugin/pulls). This project is test-driven, so keep in mind that every change and new feature should be covered by tests.
|
304 | This project uses the [semistandard code style](https://github.com/Flet/semistandard).
|
305 |
|
306 | # License
|
307 |
|
308 | This project is licensed under [MIT](https://github.com/ampedandwired/html-webpack-plugin/blob/master/LICENSE).
|