141 lines
4.1 KiB
Markdown
141 lines
4.1 KiB
Markdown
HTML Webpack Plugin
|
|
===================
|
|
|
|
This is a [webpack](http://webpack.github.io/) 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 or supply
|
|
your own template (using [blueimp templates](https://github.com/blueimp/JavaScript-Templates)).
|
|
|
|
Installation
|
|
------------
|
|
Install the plugin with npm:
|
|
```shell
|
|
$ npm install html-webpack-plugin --save-dev
|
|
```
|
|
|
|
|
|
Basic Usage
|
|
-----------
|
|
|
|
The plugin will generate an HTML5 file for you that includes all your webpack
|
|
bundles in the body using `script` tags. Just add the plugin to your webpack
|
|
config as follows:
|
|
|
|
```javascript
|
|
var HtmlWebpackPlugin = require('html-webpack-plugin')
|
|
var webpackConfig = {
|
|
entry: 'index.js',
|
|
output: {
|
|
path: 'dist',
|
|
filename: 'index_bundle.js'
|
|
},
|
|
plugins: [new HtmlWebpackPlugin()]
|
|
}
|
|
```
|
|
|
|
This will generate a file `dist/index.html` containing the following:
|
|
```html
|
|
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-type" content="text/html; charset=utf-8"/>
|
|
<title>Webpack App</title>
|
|
</head>
|
|
<body>
|
|
<script src="index_bundle.js"></script>
|
|
</body>
|
|
</html>
|
|
```
|
|
|
|
If you have multiple webpack entry points, they will all be included with `script`
|
|
tags in the generated HTML.
|
|
|
|
|
|
Configuration
|
|
-------------
|
|
You can pass a hash of configuration options to `HtmlWebpackPlugin`.
|
|
Allowed values are as follows:
|
|
|
|
- `title`: The title to use for the generated HTML document.
|
|
|
|
Here's an example webpack config illustrating how to use these options:
|
|
```javascript
|
|
{
|
|
entry: 'index.js',
|
|
output: {
|
|
path: 'dist',
|
|
filename: 'index_bundle.js'
|
|
},
|
|
plugins: [
|
|
new HtmlWebpackPlugin({
|
|
title: 'My App'
|
|
})
|
|
]
|
|
}
|
|
```
|
|
|
|
Writing Your Own Templates
|
|
--------------------------
|
|
If the default generated HTML doesn't meet your needs you can supply
|
|
your own [blueimp template](https://github.com/blueimp/JavaScript-Templates).
|
|
The [default template](https://github.com/ampedandwired/html-webpack-plugin/blob/master/default_index.html)
|
|
is a good starting point for writing your own.
|
|
|
|
Let's say for example you wanted to put a webpack bundle into the head of your
|
|
HTML as well as the body. Your template might look like this:
|
|
```html
|
|
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-type" content="text/html; charset=utf-8"/>
|
|
<title>My App</title>
|
|
<script src="{%=o.htmlWebpackPlugin.assets.head%}"></script>
|
|
</head>
|
|
<body>
|
|
<script src="{%=o.htmlWebpackPlugin.assets.main%}"></script>
|
|
</body>
|
|
</html>
|
|
```
|
|
|
|
To use this template, simply configure the plugin like this:
|
|
```javascript
|
|
{
|
|
entry: 'index.js',
|
|
output: {
|
|
path: 'dist',
|
|
filename: 'index_bundle.js'
|
|
},
|
|
plugins: [
|
|
new HtmlWebpackPlugin({
|
|
template: 'src/assets/my_template.html'
|
|
})
|
|
]
|
|
}
|
|
```
|
|
|
|
The `o` variable in the template is the data that is passed in when the
|
|
template is rendered. This variable has the following attributes:
|
|
- `htmlWebpackPlugin`: data specific to this plugin
|
|
- `htmlWebpackPlugin.assets`: a massaged representation of the
|
|
`assetsByChunkName` attribute of webpack's [stats](https://github.com/webpack/docs/wiki/node.js-api#stats)
|
|
object. It contains a mapping from entry point name to the bundle filename, eg:
|
|
```json
|
|
"htmlWebpackPlugin": {
|
|
"assets": {
|
|
"head": "assets/head_bundle.js",
|
|
"main": "assets/main_bundle.js"
|
|
}
|
|
}
|
|
```
|
|
If you've set a publicPath in your webpack config this will be reflected
|
|
correctly in this assets hash.
|
|
|
|
- `htmlWebpackPlugin.options`: the options hash that was passed to
|
|
the plugin. In addition to the options actually used by this plugin,
|
|
you can use this hash to pass arbitrary data through to your template.
|
|
|
|
- `webpack`: the webpack [stats](https://github.com/webpack/docs/wiki/node.js-api#stats)
|
|
object. Note that this is the stats object as it was at the time the HTML template
|
|
was emitted and as such may not have the full set of stats that are available
|
|
after the wepback run is complete.
|