HTML Loader

Exports HTML as `{String}` or template `{Function}`

Install

npm i -D html-loader

Usage

By default all assets (<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

⚠️ 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

webpack.config.js

{
  test: /\.html$/,
  use: {
    loader: 'html-loader',
    options: {}
  }
}

Caching

If your application includes many HTML Components or certain HTML Components are of significant size, we highly recommend to use the cache-loader for persistent caching (faster rebuilds)

webpack.config.js

{
  test: /\.html$/,
  use: [
    'cache-loader',
    {
      loader: 'html-loader',
      options: {}
    }
  ]
}

Options

Name	Type	Default	Description
url	{Boolean}	true	Enable/Disable HTML Assets (<img src="./file.png">)
import	{Boolean}	true	Enable/Disable HTML Imports (<import src="./file.html">)
template	{Boolean|String}	false	Export HTML as a template {Function}. The template placeholder defaults to <div>${ _.x }</div> (_)
minimize	{Boolean}	false	Enable/Disable HTML Minification

url

webpack.config.js

{
  loader: 'html-loader',
  options: {
    url: // TODO add URL filter method (#158 && #159)
  }
}

import

import.html

<div class="import">Import</div>

file.html

<div>
  <import src="./import.html"></import>
</div>

webpack.config.js

{
  loader: 'html-loader',
  options: {
    import: // TODO add URL filter method (#158)
  }
}

template

{Boolean}

file.html

<div>
  <p>${ _.txt }</p>
</div>

file.js

import template from './file.html'

const html = template({ txt: 'Hello World!' })

document.body.innerHTML = html

webpack.config.js

{
  loader: 'html-loader',
  options: {
    template: true
  }
}

{String}

Sets a custom placeholder for your template {Function}

file.html

<div>
  <p>${ $.txt }</p>
</div>

file.js

import template from './file.html'

const html = template({ txt: 'Hello World!' })

document.body.innerHTML = html

webpack.config.js

{
  loader: 'html-loader',
  options: {
    template: '$'
  }
}

minimize

{Boolean}

webpack.config.js

{
  loader: 'html-loader',
  options: {
    minimize: true
  }
}

{Object}

Set custom options for minification

webpack.config.js

{
  loader: 'html-loader',
  options: {
    minimize: {...options}
  }
}

Examples

HMR

component.js

import template from "./component.html";

const component = document.createElement('div')
component.innerHTML = template({ hello: 'Hello World!' })

document.body.appendChild(component);

// HMR Interface
if (module.hot) {
  // Capture hot update
  module.hot.accept('./component.html', () => {
    // Replace old content with the hot loaded one
    component.innerHTML = template({...locals})
  })
}

Extract

A very common scenario is exporting the HTML into their own .html file, to serve them directly instead of injecting with javascript. This can be achieved with a combination of following 3 loaders

• file-loader
• extract-loader
• html-loader

The html-loader will parse the URLs, require the images and everything you expect. The extract-loader will parse the javascript back into a proper HTML file, ensuring images are required and point to the proper path, and finally the file-loader will write the .html file for you

webpack.config.js

{
  test: /\.html$/,
  use: [
    {
      loader: 'file-loader'
      options: { name: '[path][name].[ext]'}
    },
    'extract-loader'
    'html-loader'
  ]
}

CSS Modules

file.css

.container {
  color: red;
}

file.html

<div class=${ _.container }></div>

webpack.config.js

[
  {
    test: /\.html$/
    use: {
      loader: 'html-loader'
      options: {
        template: true
      }
    }
  },
  {
    test: /\.css$/
    use: [
      'style-loader',
      'css-loader'
      {
        loader: 'postcss-loader',
        options: {
          ident: 'postcss',
          plugins () {
            return [
              require('postcss-modules')()
            ]
          }
        }
      }
    ]
  }
]

component.js

import * as styles from './file.css'
import template from './file.html'

const html = template({ ...styles })

document.body.innerHTML = html

Maintainers

Hemanth	Joshua Wiens	Michael Ciniawsky	Imvetri
Andrei Crnković	Yuta Hiroto	Vesselin Petrunov	Gajus Kuizinas