Skip to content

Commit c237902

Browse files
webdiscuswebdiscus
committed
docs: update readme
1 parent 88b6c2b commit c237902

1 file changed

Lines changed: 57 additions & 26 deletions

File tree

‎README.md‎

Lines changed: 57 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -18,11 +18,12 @@
1818

1919
## HTML template as entry point
2020

21-
> Define your **source files** of scripts, styles and images directly in HTML template.
21+
> This plugin allows using a template file as an [entry point](#option-entry).
22+
23+
The **HTML Bundler** generates static HTML or [template function](#template-in-js) from [any template](#template-engine) containing source files of scripts, styles, images, fonts and other resources, similar to how it works in [Vite](https://vitejs.dev/guide/#index-html-and-project-root).
24+
25+
A template imported in JS will be compiled into [template function](#template-in-js). You can use the **template function** in JS to render the template with variables in runtime on the client-side in the browser.
2226

23-
The **Bundler Plugin** generates static HTML or [template function](#template-in-js) from [any template](#template-engine) containing source files of scripts, styles, images, fonts and other resources, similar to how it works in [Vite](https://vitejs.dev/guide/#index-html-and-project-root) or [Parcel](https://parceljs.org/).
24-
This plugin allows using a template file as an [entry point](#option-entry).
25-
You can import a template into JS as a compiled [template function](#template-in-js) and render it with variables in runtime on the client-side in the browser.
2627

2728
This plugin is an **advanced successor** to `html-webpack-plugin` and a replacement of the [plugins and loaders](#list-of-plugins).
2829

@@ -100,7 +101,7 @@ You can use a relative path or Webpack alias to a source file.
100101
---
101102

102103
### 📋 [Table of Contents](#contents)
103-
### 🛠️ [Install and Quick Start](#install)
104+
### 🚀 [Install and Quick Start](#install)
104105
### 🖼 [Usage examples](#usage-examples)
105106

106107
---
@@ -257,7 +258,7 @@ npm install css-loader sass-loader sass --save-dev
257258
Start with an HTML template. Add the `<link>` and `<script>` tags.
258259
You can include asset source files such as SCSS, JS, images, and other media files directly in an HTML template.
259260

260-
The plugin resolves `<script src="...">` `<link href="...">` and `<img src="...">` that references your script, style and image source files.
261+
The plugin resolves `<script src="...">` `<link href="...">` and `<img src="..." srcset="...">` that references your script, style and image source files.
261262

262263
For example, there is the template _./src/views/home.html_:
263264

@@ -274,15 +275,14 @@ For example, there is the template _./src/views/home.html_:
274275
<script src="./main.js" defer="defer"></script>
275276
</head>
276277
<body>
277-
<!-- variable from Webpack config -->
278-
<h1>Hello <%= name %>!</h1>
278+
<h1>Hello World!</h1>
279279
<!-- relative path to image source file -->
280280
<img src="./picture.png" />
281281
</body>
282282
</html>
283283
```
284284

285-
All source filenames should be relative to the current HTML template, or you can use [Webpack alias](https://webpack.js.org/configuration/resolve/#resolvealias).
285+
All source filenames should be relative to the entrypoint template, or you can use [Webpack alias](https://webpack.js.org/configuration/resolve/#resolvealias).
286286
The references are rewritten in the generated HTML so that they link to the correct output files.
287287

288288
The generated HTML contains URLs of the output filenames:
@@ -319,21 +319,40 @@ const HtmlBundlerPlugin = require('html-bundler-webpack-plugin');
319319
module.exports = {
320320
plugins: [
321321
new HtmlBundlerPlugin({
322-
// define many page templates manually
322+
// automatically processing all templates in the path
323+
entry: 'src/views/',
324+
325+
// - OR - define pages manually (key is output filename w/o `.html`)
323326
entry: {
324-
// advanced page config with external variables passed into template
325-
index: { // => dist/index.html
327+
index: 'src/views/home.html', // => dist/index.html
328+
'news/sport': 'src/views/news/sport/index.html', // => dist/news/sport.html
329+
},
330+
331+
// - OR - define pages with variables
332+
entry: [
333+
{
326334
import: 'src/views/home.html', // template file
327-
data: { title: 'Homepage', name: 'World' }, // pass variables into template
335+
filename: 'index.html', // => dist/index.html
336+
data: { title: 'Homepage' }, // pass variables into template
328337
},
338+
{
339+
import: 'src/views/news/sport/index.html', // template file
340+
filename: 'news/sport.html', // => dist/news/sport.html
341+
data: { title: 'Sport news' }, // pass variables into template
342+
},
343+
],
344+
345+
// - OR - combine both the pages with and w/o variables in one entry
346+
entry: {
329347
// simple page config w/o variables
330-
about: 'src/views/about.html', // => dist/about.html
331-
'news/sport': 'src/views/news/sport/index.html', // => dist/news/sport.html
332-
// add more templates if needed
333-
// 'another-page': 'src/views/anotherPage.html', // => dist/another-page.html
348+
index: 'src/views/home.html', // => dist/index.html
349+
// advanced page config with variables
350+
'news/sport': { // => dist/news/sport.html
351+
import: 'src/views/home.html', // template file
352+
data: { title: 'Sport news' }, // pass variables into template
353+
},
334354
},
335-
// - OR - define a relative or absolute path to page templates
336-
entry: 'src/views/',
355+
337356
js: {
338357
// JS output filename, used if `inline` option is false (defaults)
339358
filename: 'js/[name].[contenthash:8].js',
@@ -560,7 +579,12 @@ See [boilerplate](https://github.com/webdiscus/webpack-html-scss-boilerplate)
560579
(\*) - `asset/source` works currently for SVG only, in a next version will work for other files too
561580

562581
<a id="list-of-plugins" name="list-of-plugins"></a>
563-
Just one HTML bundler plugin replaces the functionality of the plugins and loaders:
582+
583+
#### Why do many developers switch from Webpack to other bundlers?
584+
One of the reasons they cite is the complex configuration many different plugins and loaders for one simple thing - rendering an HTML page with assets.
585+
586+
The HTML bundler plugin "changes the rule of the game", making configuration very simple and clear.
587+
Just one plugin replaces the functionality of the plugins and loaders:
564588

565589
| Package | Features |
566590
|---------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
@@ -576,12 +600,12 @@ Just one HTML bundler plugin replaces the functionality of the plugins and loade
576600
| [posthtml-inline-svg](https://github.com/andrey-hohlov/posthtml-inline-svg) | injects an inline SVG icon into HTML |
577601
| [resolve-url-loader](https://github.com/bholloway/resolve-url-loader) | resolves a relative URL in CSS |
578602
| [svg-url-loader](https://github.com/bhovhannes/svg-url-loader) | encodes a SVG data-URL as utf8 |
579-
| [handlebars-webpack-plugin](https://github.com/sagold/handlebars-webpack-plugin) | renders handlebars templates |
580-
| [handlebars-loader](https://github.com/pcardune/handlebars-loader) | import a templates function in JS on client-side |
581603
| [webpack-subresource-integrity ](https://www.npmjs.com/package/webpack-subresource-integrity) | enables Subresource Integrity |
582604
| [favicons-webpack-plugin ](https://github.com/jantimon/favicons-webpack-plugin) | generates favicons and icons |
583-
584-
605+
| [handlebars-webpack-plugin](https://github.com/sagold/handlebars-webpack-plugin) | renders Handlebars templates |
606+
| [handlebars-loader](https://github.com/pcardune/handlebars-loader) | compiles Handlebars templates |
607+
| [pug-loader](https://www.npmjs.com/package/pug-loader) | compiles Pug templates |
608+
| [nunjucks-loader](https://github.com/at0g/nunjucks-loader) | compiles Nunjucks templates |
585609

586610

587611
#### [↑ back to contents](#contents)
@@ -1208,14 +1232,21 @@ The content of the `dist/integrity.json` file looks like:
12081232
12091233
### `test`
12101234
1211-
Type: `RegExp` Default: `/\.(html|ejs|eta|hbs|handlebars|njk)$/`
1235+
Type: `RegExp` Default: `/\.(html|eta)$/`
12121236
12131237
The `test` option allows to handel only those templates as entry points that match the name of the source file.
12141238
12151239
For example, if you have other templates, e.g. `*.liquid`, as entry points, then you can set the option to match custom template files: `test: /\.(html|liquid)$/`.
12161240
12171241
The `test` value is used in the [default loader](#loader-options).
12181242
1243+
> **Note**
1244+
>
1245+
> Using the [preprocessor](#loader-option-preprocessor) options will be added the templating engine extensions in the `test` automatically.
1246+
> Defaults `preprocessor` is [Eta](#loader-option-preprocessor-options-eta) therefore is used the `/\.(html|eta)$/` RegExp.
1247+
>
1248+
> For example, if you define the preprocessor option as the [handlebars](#loader-option-preprocessor-options-handlebars), then will be used the `/\.(html|hbs|handlebars)$/` RegExp automatically.
1249+
12191250
**Why is it necessary to define it? Can't it be automatically processed?**
12201251
12211252
This plugin is very powerful and has many experimental features not yet documented.
@@ -2729,7 +2760,7 @@ The `default loader`:
27292760
27302761
```js
27312762
{
2732-
test: /\.(html|ejs|eta|hbs|handlebars|njk)$/,
2763+
test: /\.(html)$/,
27332764
loader: HtmlBundlerPlugin.loader,
27342765
}
27352766
```

0 commit comments

Comments
 (0)