Add migration guide
This commit is contained in:
Jan Nicklas
Jan Nicklas
parent
70df65d9e5
commit
cd77e8a727
|
|
@ -16,6 +16,13 @@ Install the plugin with npm:
|
|||
$ npm install html-webpack-plugin@2 --save-dev
|
||||
```
|
||||
|
||||
Migration guide from 1.x
|
||||
------------------------
|
||||
|
||||
Please see the guide [https://github.com/ampedandwired/html-webpack-plugin/blob/master/migration.md]
|
||||
In case I missed something please open a pull request for it.
|
||||
See also issue [#186](https://github.com/ampedandwired/html-webpack-plugin/issues/186)
|
||||
|
||||
Basic Usage
|
||||
-----------
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,157 @@
|
|||
# Migrating from 1.x to 2.x
|
||||
|
||||
## Default config
|
||||
|
||||
https://github.com/ampedandwired/html-webpack-plugin/tree/master/examples/default
|
||||
|
||||
As of 2.x the `inject` options is set to true by default which means that all your javascript, css files and manifest files are injected automatically. See https://github.com/ampedandwired/html-webpack-plugin#configuration
|
||||
|
||||
The default template has changed according to the inject option - but should behave like the previous version did.
|
||||
|
||||
|
||||
```js
|
||||
var HtmlWebpackPlugin = require('html-webpack-plugin');
|
||||
|
||||
module.exports = {
|
||||
// ...
|
||||
plugins: [
|
||||
new HtmlWebpackPlugin()
|
||||
]
|
||||
};
|
||||
```
|
||||
|
||||
## Custom template
|
||||
|
||||
This inject feature aims to simpify your custom templates:
|
||||
https://github.com/ampedandwired/html-webpack-plugin/tree/master/examples/custom-template
|
||||
|
||||
```js
|
||||
var HtmlWebpackPlugin = require('html-webpack-plugin');
|
||||
|
||||
module.exports = {
|
||||
// ...
|
||||
plugins: [
|
||||
new HtmlWebpackPlugin({
|
||||
template: 'template.html'
|
||||
})
|
||||
]
|
||||
};
|
||||
```
|
||||
|
||||
```html
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>Webpack App</title>
|
||||
</head>
|
||||
<body>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
Although we did not specify any script tags or link tags they will be injected automatically and the result will be:
|
||||
```html
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>Webpack App</title>
|
||||
<link href="styles.css" rel="stylesheet">
|
||||
</head>
|
||||
<body>
|
||||
<script src="bundle.js"></script>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
## Tempalting and variables
|
||||
|
||||
As of 2.x blueimp was replaced by lodash/underscore/ejs templates as they are more common.
|
||||
This also removes the `o` in template variables. ` <body class="{%= o.htmlWebpackPlugin.options.environment %}">` becomes `<body class="<%= htmlWebpackPlugin.options.environment %>">` it also allows to escape variables by using `<%-` instead of `<%=` to prevent unexpected behaviours: `<body class="<%- htmlWebpackPlugin.options.environment %>">`
|
||||
|
||||
# Loaders in templates
|
||||
Loaders may now be used inside the template the same way as you would expect in your javascript files.
|
||||
For the following example you would have to configure a html and url/file-loader:
|
||||
|
||||
```html
|
||||
<link rel="apple-touch-icon" href="<%- require('../images/favicons/apple-icon-60x60.png') %>">
|
||||
<%= require('partial.html'); %>
|
||||
```
|
||||
|
||||
## Custom template engines
|
||||
|
||||
Maybe you prefer jade or blueimp over underscore - or your project is using jade for the front end part.
|
||||
With 2.x you can use the webpack loaders either once only for the template as in the following example.
|
||||
where we use jade (requires the [jade-loader](https://github.com/webpack/jade-loader)):
|
||||
|
||||
```js
|
||||
var HtmlWebpackPlugin = require('html-webpack-plugin');
|
||||
|
||||
module.exports = {
|
||||
// ...
|
||||
plugins: [
|
||||
new HtmlWebpackPlugin({
|
||||
template: 'jade!template.jade'
|
||||
})
|
||||
]
|
||||
};
|
||||
```
|
||||
|
||||
or by configuring webpack to handle all `.jade` files:
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
// ...
|
||||
module: {
|
||||
loaders: [
|
||||
{ test: /\.jade$/, loader: 'jade' }
|
||||
]
|
||||
},
|
||||
plugins: [
|
||||
new HtmlWebpackPlugin({
|
||||
template: 'template.jade'
|
||||
})
|
||||
]
|
||||
};
|
||||
```
|
||||
|
||||
Please note that if you specify the loader and use 'jade!template.jadde' webpack will try to apply the jade loader twice and fail.
|
||||
|
||||
## Isomorph apps
|
||||
|
||||
As of the loader changes in 2.x the `templateContent` was removed.
|
||||
However you can still use custom javascript functions to generate a template:
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
// ...
|
||||
plugins: [
|
||||
new HtmlWebpackPlugin({
|
||||
template: 'template.js'
|
||||
})
|
||||
]
|
||||
};
|
||||
```
|
||||
Simple template.js
|
||||
```js
|
||||
module.exports = '<html>...</html>';
|
||||
```
|
||||
More advanced template.js
|
||||
```js
|
||||
module.exports = function(compilationResult, chunks, assets, compilation) {
|
||||
return '<html>..</html>';
|
||||
};
|
||||
```
|
||||
Using loaders inside a template.js
|
||||
```js
|
||||
// This function has to return a string or promised string:
|
||||
module.exports = function(compilationResult, chunks, assets, compilation) {
|
||||
// Play around with the arguments and then use the webpack jade loader to load the jade:
|
||||
return require('./template.jade')({assets: assets});
|
||||
};
|
||||
```
|
||||
|
||||
Unfortunately `__dirname` does not work correctly.
|
||||
If someone know why I would love to merge a pull request.
|
||||
A good start point might be here: https://github.com/webpack/webpack/issues/135
|
||||
Loading…
Reference in New Issue