Skip to content

Commit a9627b7

Browse files
michael-ciniawskymichael-ciniawsky
committed
[squash] docs(README): updates
1 parent cc116a9 commit a9627b7

File tree

2 files changed

+172
-15
lines changed

2 files changed

+172
-15
lines changed

‎README.md

Lines changed: 169 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
[![chat][chat]][chat-url]
77

88
<div align="center">
9-
<img width="200" height="200"
9+
<img width="180" height="180"
1010
src="https://worldvectorlogo.com/logos/html5.svg">
1111
<a href="https://github.com/webpack/webpack">
1212
<img width="200" height="200"
@@ -24,10 +24,11 @@ npm i -D html-loader
2424

2525
<h2 align="center">Usage</h2>
2626

27-
By default every assets (`<img src="./image.png">`) is transpiled to it's own module request (`import HTML__URL__O from './image.png'`) to be correctly handled by `webpack`.
27+
By default asset requests (`<img src="./image.png">`) are transpiled to their own module requests (`import HTML__URL__O from './image.png'`) to be correctly handled by `webpack` as an ES Module
2828

29-
> ⚠️ You need to specify loaders for your assets (e.g images) separately in your `webpack.config.js`, like the `file-loader` or `url-loader`, to handle these requests.
29+
> ⚠️ You need to specify additional loaders for your assets (e.g images) separately in your `webpack.config.js`, like the `file-loader` or `url-loader`, to handle these requests.
3030
31+
**webpack.config.js**
3132
```js
3233
{
3334
test: /\.html$/,
@@ -38,13 +39,33 @@ By default every assets (`<img src="./image.png">`) is transpiled to it's own mo
3839
}
3940
```
4041

42+
### `Caching`
43+
44+
If your application includes many HTML Components or certain Components are of significant size, we highly recommend to use the [`cache-loader`](https://github.com/webpack-contrib/cache-loader) for persistent caching these components for faster rebuilds
45+
46+
**webpack.config.js**
47+
```js
48+
{
49+
test: /\.html$/,
50+
use: [
51+
'cache-loader',
52+
{
53+
loader: 'html-loader',
54+
options: {}
55+
}
56+
]
57+
}
58+
```
59+
60+
4161
<h2 align="center">Options</h2>
4262

4363
|Name|Type|Default|Description|
4464
|:--:|:--:|:-----:|:----------|
45-
|**`url`**|`{Boolean}`|`true`| Enable/Disable HTML Assets (`<img src="./file.png">`)|
46-
|**`import`** |`{Boolean}`|`true`| Enable/Disable HTML Imports (`<import src="./file.html">`)|
47-
|**`template`**|`{Boolean}`|`false`|Export HTML as a template `{Function}`|
65+
|**[`url`](#url)**|`{Boolean}`|`true`| Enable/Disable HTML Assets (`<img src="./file.png">`)|
66+
|**[`import`](#import)** |`{Boolean}`|`true`| Enable/Disable HTML Imports (`<import src="./file.html">`)|
67+
|**[`template`](#template)**|`{Boolean\|String}`|`false`|Export HTML as a template `{Function}`. The template placeholder defaults to `<div>${ _.x }</div>` (`_`)|
68+
|**[`minimize`](#minimize)**|`{Boolean}`|`false`|Enable/Disable HTML Minification|
4869

4970
### `url`
5071

@@ -74,6 +95,22 @@ By default every assets (`<img src="./image.png">`) is transpiled to it's own mo
7495

7596
#### `{Boolean}`
7697

98+
**file.html**
99+
```html
100+
<div>
101+
<p>${ _.txt }</p>
102+
</div>
103+
```
104+
105+
**file.js**
106+
```js
107+
import template from './file.html'
108+
109+
const html = template({ txt: 'Hello World!' })
110+
111+
document.body.innerHTML = html
112+
```
113+
77114
**webpack.config.js**
78115
```js
79116
{
@@ -84,21 +121,88 @@ By default every assets (`<img src="./image.png">`) is transpiled to it's own mo
84121
}
85122
```
86123

124+
#### `{String}`
125+
126+
Set a custom name for the template scope
127+
128+
**file.html**
129+
```html
130+
<div>
131+
<p>${ $.txt }</p>
132+
</div>
133+
```
134+
135+
**file.js**
136+
```js
137+
import template from './file.html'
138+
139+
const html = template({ txt: 'Hello World!' })
140+
141+
document.body.innerHTML = html
142+
```
143+
144+
**webpack.config.js**
145+
```js
146+
{
147+
loader: 'html-loader',
148+
options: {
149+
template: '$'
150+
}
151+
}
152+
```
153+
154+
### `minimize`
155+
156+
#### `{Boolean}`
157+
158+
**webpack.config.js**
159+
```js
160+
{
161+
loader: 'html-loader',
162+
options: {
163+
minimize: true
164+
}
165+
}
166+
```
167+
87168
#### `{Object}`
88169

170+
Pass custom [options](https://github.com/posthtml/htmlnano#modules) for minification
171+
89172
**webpack.config.js**
90173
```js
91174
{
92175
loader: 'html-loader',
93176
options: {
94-
template: { ...locals } // TODO add method to pass locals
177+
minimize: {...options}
95178
}
96179
}
97180
```
98181

99182
<h2 align="center">Examples</h2>
100183

101-
### `Extract HTML`
184+
### `HMR`
185+
186+
**component.js**
187+
```js
188+
import template from "./component.html";
189+
190+
const component = document.createElement('div')
191+
component.innerHTML = template({ hello: 'Hello World!' })
192+
193+
document.body.appendChild(component);
194+
195+
// HMR Interface
196+
if (module.hot) {
197+
// Capture hot update
198+
module.hot.accept('./component.html', () => {
199+
// Replace old content with the hot loaded one
200+
component.innerHTML = template({...locals})
201+
})
202+
}
203+
```
204+
205+
### `Extract`
102206

103207
A very common scenario is exporting the HTML into their own `.html` file, to
104208
serve them directly instead of injecting with javascript. This can be achieved
@@ -127,6 +231,63 @@ file, ensuring images are required and point to the proper path, and finally the
127231
}
128232
```
129233

234+
### `CSS Modules`
235+
236+
**file.css**
237+
```css
238+
.container {
239+
color: red;
240+
}
241+
```
242+
243+
**file.html**
244+
```html
245+
<div class=${ _.container }></div>
246+
```
247+
248+
**webpack.config.js**
249+
```js
250+
[
251+
{
252+
test: /\.html$/
253+
use: {
254+
loader: 'html-loader'
255+
options: {
256+
template: true
257+
}
258+
}
259+
},
260+
{
261+
test: /\.css$/
262+
use: [
263+
'style-loader',
264+
'css-loader'
265+
{
266+
loader: 'postcss-loader',
267+
options: {
268+
ident: 'postcss',
269+
plugins () {
270+
return [
271+
require('postcss-modules')()
272+
]
273+
}
274+
}
275+
}
276+
]
277+
}
278+
]
279+
```
280+
281+
**component.js**
282+
```js
283+
import * as styles from './file.css'
284+
import template from './file.html'
285+
286+
const html = template({...styles})
287+
288+
document.body.innerHTML = html
289+
```
290+
130291
<h2 align="center">Maintainers</h2>
131292

132293
<table>

‎src/index.js

Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ import LoaderError from './lib/Error';
1414
const defaults = {
1515
url: true,
1616
import: true,
17+
minimize: false,
1718
template: false,
1819
};
1920

@@ -53,17 +54,12 @@ export default function loader(html) {
5354

5455
const imports = '\n';
5556

56-
// #120 - Support exporting a template function
57-
//
58-
// import template from 'file.html'
59-
//
60-
// const html = template({...locals})
61-
const locals = typeof options.template === 'string'
57+
const template = typeof options.template === 'string'
6258
? options.template
6359
: '_';
6460

6561
const html = options.template
66-
? `function (${locals}) { return \`${result.html}\`; }`
62+
? `function (${template}) { return \`${result.html}\`; }`
6763
: `\`${result.html}\``
6864

6965
result = [

0 commit comments

Comments
 (0)