HTML Bundler Plugin for Webpack

Generates HTML with JS and CSS from templates containing source files of scripts, styles and other assets.
Advanced alternative to html-webpack-plugin and modern replacement of many plugins and loaders.

📋 Table of Contents 🚀 Install and Quick Start 🖼 Usage examples 🔆 What's New

💡 Highlights

An entry point is any HTML template. Start from HTML, not from JS.
Find and automatic processing of templates in the entry directory.
Renders the template engines "out of the box": Eta, EJS, Handlebars, Nunjucks, Pug, Tempura, TwigJS, LiquidJS. It is very easy to add support for any template engine.
Source files of script and style can be specified directly in HTML:
- <link href="./style.scss" rel="stylesheet">
  No longer need to define source style files in Webpack entry or import styles in JavaScript.
- <script src="./app.ts" defer="defer"></script>
  No longer need to define source JavaScript files in Webpack entry.
Resolves source files of assets in attributes such as href src srcset using relative path or alias:
- <link href="../images/favicon.svg" type="image/svg" rel=icon />
- <img src="@images/pic.png" srcset="@images/pic400.png 1x, @images/pic800.png 2x" />
  Source files will be resolved, processed and auto-replaced with correct URLs in the bundled output.
Inlines JS, CSS and Images into HTML. See how to inline all resources into single HTML file.
HMR for CSS - update CSS in browser without a full reload.
Recompiles the template after changes in the data file assigned to the entry page as a JSON or JS filename.
Generates the preload tags for fonts, images, video, scripts, styles.
Generates the integrity attribute in the link and script tags.
Generates the favicons of different sizes for various platforms.
You can create own plugin using the Plugin Hooks.
Over 600 tests for various use cases.

See full list of features.

HTML template as entry point

The HTML Bundler generates static HTML or template function from various templates containing source files of scripts, styles, images, fonts and other resources, similar to how it works in Vite. This plugin looks at the template files in entry option to start building the bundle. The source files of dependencies (scripts, styles, etc.) can be defined directly in the template.

The plugin resolves source files of assets in templates and replaces them with correct output URLs in the generated HTML. The resolved assets will be processed via Webpack plugins/loaders and placed into the output directory. You can use a relative path or Webpack alias to a source file.

A template imported in JS will be compiled into template function. You can use the template function in JS to render the template with variables in runtime on the client-side in the browser.

For example, using source asset files is HTML template ./src/views/index.html:

<html>
  <head>
    <!-- relative path to SCSS source file -->
    <link href="../scss/style.scss" rel="stylesheet" />
    <!-- relative path to TypeScript source file -->
    <script src="../app/main.ts" defer="defer"></script>
  </head>
  <body>
    <h1>Hello World!</h1>
    <!-- relative path to image source file -->
    <img src="../assets/images/picture1.png" />
    <!-- Webpack alias as path (src/assets/images/) to image source file -->
    <img src="@images/picture2.png" />
  </body>
</html>

The folder structure of the example:

./src/views/index.html
./src/app/main.ts
./src/scss/style.scss
./src/assets/images/picture1.png
./src/assets/images/picture2.png

Simple and clear Webpack configuration:

const path = require('path');
const HtmlBundlerPlugin = require('html-bundler-webpack-plugin');

module.exports = {
  output: {
    path: path.resolve(__dirname, 'dist'),
  },

  plugins: [
    new HtmlBundlerPlugin({
     // all the necessary options are in one place
      entry: {
        index: 'src/views/index.html', // save generated HTML into dist/index.html
      },
      js: {
        filename: 'js/[name].[contenthash:8].js', // JS output filename
      },
      css: {
        filename: 'css/[name].[contenthash:8].css', // CSS output filename
      },
    }),
  ],
  
  module: {
      rules: [
        {
          test: /\.s?css$/,
          use: ['css-loader', 'sass-loader'],
        },
        {
          test: /\.(ico|png|jp?g|svg)/,
          type: 'asset/resource',
        },
      ],
    },
};

See full list of all plugin options.

Open an example in StackBlitz

🦖 Mozilla already uses this plugin to build static HTML files for the Mozilla AI GUIDE site.

The plugin has been actively developed for more than 2 years, and since 2023 it is open source.
Please support this project by giving it a star ⭐.

❤️ Sponsors & Patrons

Thank you to all our sponsors and patrons!

⚙️ How works the plugin

The plugin resolves references in the HTML template and adds them to the Webpack compilation. Webpack will automatically process the source files, and the plugin replaces the references with their output filenames in the generated HTML. See how the plugin works under the hood.

❓Question / Feature Request / Bug

If you have discovered a bug or have a feature suggestion, feel free to create an issue on GitHub.

📚 Read it

🔆 What's New in v4

NEW added supports the HMR for CSS (since v4.5.0).
NEW added supports the multiple configurations.
SUPPORTS Webpack version 5.96+ (since v4.2.0).
SUPPORTS Webpack version 5.81+ (since v4.0.0).
SUPPORTS Node.js version 18+.
BREAKING CHANGES see in the changelog.

🔆 What's New in v3

NEW added supports the template function in JS runtime on the client-side.
NEW added Pug preprocessor.
NEW added Twig preprocessor.
NEW added supports the dynamic import of styles.
NEW added supports the CSS Modules for styles imported in JS.
NEW added CSS extraction from styles used in *.vue files.
NEW added Hooks & Callbacks. Now you can create own plugin to extend this plugin.
NEW added the build-in FaviconsBundlerPlugin to generate and inject favicon tags.

🔆 What's New in v2

NEW added importing style files in JavaScript.
NEW added support the integrity.
NEW you can add/delete/rename a template file in the entry path without restarting Webpack.

For full release notes see the changelog.

⚠️ Limitations

Cache type

The current version works stably with cache.type as 'memory' (Webpack's default setting).

Support for the 'filesystem' cache type is in beta. It works stably in standard use cases, but it cannot be guaranteed to work in all use cases. If you have any problems, feel free to create an issue.

Install and Quick start

Install the html-bundler-webpack-plugin:

npm install html-bundler-webpack-plugin --save-dev

It's recommended to combine html-bundler-webpack-plugin with the css-loader and the sass-loader.
Install additional packages for styles:

npm install css-loader sass-loader sass --save-dev

Start with an HTML template. Add the <link> and <script> tags. You can include asset source files such as SCSS, JS, images, and other media files directly in an HTML template.

The plugin resolves <script src="..."> <link href="..."> and <img src="..." srcset="..."> that references your script, style and image source files.

For example, there is the template ./src/views/home.html:

<html>
  <head>
    <!-- variable from Webpack config -->
    <title><%= title %></title>
    <!-- relative path to favicon source file -->
    <link href="./favicon.ico" rel="icon" />
    <!-- relative path to SCSS source file -->
    <link href="./style.scss" rel="stylesheet" />
    <!-- relative path to JS source file -->
    <script src="./main.js" defer="defer"></script>
  </head>
  <body>
    <h1>Hello World!</h1>
    <!-- relative path to image source file -->
    <img src="./picture.png" />
  </body>
</html>

All source filenames should be relative to the entrypoint template, or you can use Webpack alias. The references are rewritten in the generated HTML so that they point to the correct output files.

The generated HTML contains URLs of the output filenames:

<html>
  <head>
    <title>Homepage</title>
    <link href="img/favicon.3bd858b4.ico" rel="icon" />
    <link href="css/style.05e4dd86.css" rel="stylesheet" />
    <script src="js/main.f4b855d8.js" defer="defer"></script>
  </head>
  <body>
    <h1>Hello World!</h1>
    <img src="img/picture.58b43bd8.png" />
  </body>
</html>

Pages can be defined in the entry option. JS and CSS can be configured using the js and css options.

If the entry option is a path, the plugin finds all templates automatically and keep the same directory structure in the output directory.

If the entry option is an object, the key is an output filename without .html extension and the value is a template file.

const HtmlBundlerPlugin = require('html-bundler-webpack-plugin');

module.exports = {
  plugins: [
    new HtmlBundlerPlugin({
      // automatically processing all templates in the path
      entry: 'src/views/',
      
      // - OR - define pages manually (key is output filename w/o `.html`)
      entry: {
        index: 'src/views/home.html', // => dist/index.html
        'news/sport': 'src/views/news/sport/index.html', // => dist/news/sport.html
      },
      
      // - OR - define pages with variables
      entry: [
        {
          import: 'src/views/home.html', // template file
          filename: 'index.html', // => dist/index.html
          data: { title: 'Homepage' }, // pass variables into template
        },
        {
          import: 'src/views/news/sport/index.html', // template file
          filename: 'news/sport.html', // => dist/news/sport.html
          data: { title: 'Sport news' }, // pass variables into template
        },
      ],
      
      // - OR - combine both the pages with and w/o variables in one entry
      entry: {
        // simple page config w/o variables
        index: 'src/views/home.html', // => dist/index.html
        // advanced page config with variables
        'news/sport': { // => dist/news/sport.html
          import: 'src/views/home.html', // template file
          data: { title: 'Sport news' }, // pass variables into template
        },
      },

      js: {
        // JS output filename, used if `inline` option is false (defaults)
        filename: 'js/[name].[contenthash:8].js',
        //inline: true, // inlines JS into HTML
      },
      css: {
        // CSS output filename, used if `inline` option is false (defaults)
        filename: 'css/[name].[contenthash:8].css',
        //inline: true, // inlines CSS into HTML
      },
    }),
  ],
  module: {
    rules: [
      {
        test: /\.(css|sass|scss)$/,
        use: ['css-loader', 'sass-loader'],
      },
      {
        test: /\.(ico|png|jp?g|webp|svg)$/,
        type: 'asset/resource',
        generator: {
          filename: 'img/[name].[hash:8][ext][query]',
        },
      },
    ],
  },
};

ℹ️ Note

To define the JS output filename, use the js.filename option of the plugin.
Don't use Webpack's output.filename, hold all relevant settings in one place - in plugin options.
Both places have the same effect, but js.filename has priority over output.filename.

No additional template loader is required. The plugin handles templates with base EJS-like syntax automatically. The default templating engine is Eta.

For using the native EJS syntax see Templating with EJS.
For using the Handlebars see Templating with Handlebars.
For other templates see Template engines.

For custom templates, you can use the preprocessor option to handle any template engine.

Simple example SPA
Automatically processing many HTML templates
Create multiple HTML pages	See boilerplate

Features
Install and Quick start
Webpack options
- output
  - path
  - publicPath
  - filename
- entry
Build-in Plugins
- FaviconsBundlerPlugin (generates favicon tags)
Third-party Plugins
Hooks & Callbacks
Plugin options
- test (RegEx to handle matching templates)
- entry (template as entry point)
  - entry as an array (array notation)
  - entry as an object (object notation)
  - entry as a path (find templates in a directory recursively)
  - entry data (pass data in the single template as an object or a file)
- entry dynamic (entry as a path to template files)
- entryFilter (filter for entry dynamic)
- outputPath (output path of HTML file)
- filename (output filename of HTML file)
- js (options for JS)
- css (options for CSS)
- data (🔗reference to loaderOptions.data)
- beforePreprocessor (callback, 🔗reference to loaderOptions.beforePreprocessor)
- preprocessor (callback or string, 🔗reference to loaderOptions.preprocessor)
- preprocessorOptions (🔗reference to loaderOptions.preprocessorOptions)
- postprocess (callback)
- beforeEmit (callback)
- afterEmit (callback)
- preload (inject preload link tags)
- integrity (inject subresource integrity hash into script and style tags)
- minify and minifyOptions (minification of generated HTML)
- extractComments
- watchFiles
- hotUpdate
- verbose
- loaderOptions (reference to loader options)
Loader options
- sources (processing of custom tag attributes)
- root (allow to resolve a path with leading /)
- context (allow to resolve a path w/o leading /)
- beforePreprocessor (callback)
- preprocessor (callback or string) and preprocessorOptions (templating)
  - eta
  - ejs
  - handlebars
  - tempura
  - nunjucks
  - pug
  - twig
  - custom (using any template engine)
- data (pass global data into all templates as an object or a file)
Using template engines
- Eta
- EJS
- Handlebars
- LiquidJS
- Mustache
- Nunjucks
- Pug
- Tempura
- TwigJS
Using template in JavaScript
Setup Live Reload
Recipes
Problems & Solutions
Demo sites
- Multiple page e-shop template (Handlebars) demo | source
- Asia restaurant (Nunjucks) demo | source
- 10up / Animation Best Practices demo | source
Usage examples
- Simple example "Hello World!" View in browser | source
- Simple example "Hello World!" using Pug View in browser | source
- Automatically processing multiple HTML templates View in browser | source
- Bootstrap with Webpack View in browser | source
- Tailwind CSS with Webpack View in browser | source
- Twig with Webpack View in browser
- Handlebars with Webpack View in browser | source
- Extend Handlebars layout with blocks View in browser | source
- Auto generate integrity hash for link and script tags View in browser | source
- Inline multiple SVG files w/o ID collision View in browser | source
- Bundle Vue app into single HTML file with embedded JS, CSS, images View in browser | source

Features

HTML template is the entry point for all resources
extracts JS from the source script filename specified in HTML via a <script> tag
extracts CSS from the source style filename specified in HTML via a <link> tag
importing style files in JavaScript
resolves source asset files in HTML attributes and in the CSS url(), without using resolve-url-loader
supports styles used in *.vue files
generated HTML contains output filenames
supports the module types asset/resource asset/inline asset asset/source (*)
inline CSS in HTML
inline JavaScript in HTML
inline image as base64 encoded data-URL for PNG, JPG, etc. in HTML and CSS
inline SVG as SVG tag in HTML, e.g.: <svg>...</svg>
inline SVG as utf-8 data-URL in CSS, e.g.: url("data:image/svg+xml,<svg>...</svg>")
auto generation of <link rel="preload"> to preload assets
supports the auto publicPath
enable/disable extraction of comments to *.LICENSE.txt file
supports template engines such as Eta, EJS, Handlebars, Nunjucks, Pug, TwigJS, LiquidJS and others
supports a template function for usage in JS on the client-side
supports both async and sync preprocessor
auto processing multiple HTML templates using the entry path
pass data into template from the plugin config
dynamically loading template variables using the data option, change data w/o restarting
generates the integrity hashes and adds the integrity attribute to the link and script tags
minification of generated HTML
allows extending base functionality using hooks & callbacks
generates favicons of different sizes for various platforms and injects them into HTML

(*) - asset/source works currently for SVG only, in a next version will work for other files too

Why do many developers switch from Webpack to other bundlers?

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.

The HTML bundler plugin "changes the rule of the game", making configuration very simple and clear. Just one plugin replaces the functionality of the plugins and loaders:

Package	Features
html-webpack-plugin	creates HTML and inject `script` tag for compiled JS file into HTML
mini-css-extract-plugin	injects `link` tag for processed CSS file into HTML
webpack-remove-empty-scripts	removes generated empty JS files
html-loader	exports HTML, resolving attributes
style-loader	injects an inline CSS into HTML
html-webpack-inject-preload	inject preload link tags
preload-webpack-plugin	inject preload link tags
html-webpack-inline-source-plugin	inline JS and CSS into HTML
html-inline-css-webpack-plugin	inline CSS into HTML
posthtml-inline-svg	injects an inline SVG icon into HTML
resolve-url-loader	resolves a relative URL in CSS
svg-url-loader	encodes a SVG data-URL as utf8
webpack-subresource-integrity	enables Subresource Integrity
favicons-webpack-plugin	generates favicons and icons
handlebars-webpack-plugin	renders Handlebars templates
handlebars-loader	compiles Handlebars templates
pug-loader	compiles Pug templates
nunjucks-loader	compiles Nunjucks templates

Name		Name	Last commit message	Last commit date
Latest commit History 223 Commits
.github		.github
examples		examples
experiments/rspack		experiments/rspack
images		images
plugins		plugins
src		src
test		test
.codecov.yml		.codecov.yml
.gitignore		.gitignore
.npmignore		.npmignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
types.d.ts		types.d.ts

Tag	Attributes
`link`	`href` for `type="text/css"` `rel="stylesheet"` `as="style"` `as="script"` `imagesrcset` for `as="image"`
`script`	`src`
`img`	`src` `srcset`
`image`	`href` `xlink:href`
`use`	`href` `xlink:href`
`input`	`src` (for `type="image"`)
`source`	`src` `srcset`
`audio`	`src`
`track`	`src`
`video`	`src` `poster`
`object`	`data`

License

webdiscus/html-bundler-webpack-plugin

Folders and files

Latest commit

History

Repository files navigation

📋 Table of Contents 🚀 Install and Quick Start 🖼 Usage examples 🔆 What's New

💡 Highlights

HTML template as entry point

❤️ Sponsors & Patrons

⚙️ How works the plugin

❓Question / Feature Request / Bug

📚 Read it

🔆 What's New in v4

🔆 What's New in v3

🔆 What's New in v2

⚠️ Limitations

Cache type

Install and Quick start

Table of Contents

Features

Why do many developers switch from Webpack to other bundlers?

Webpack options

output.path

output.publicPath

output.filename

entry

Build-in Plugins

FaviconsBundlerPlugin

Install

Config

FaviconsBundlerPlugin options

Usage

Third-party Plugins

Hooks & Callbacks

When using callbacks

When using hooks

How to use hooks

beforePreprocessor

preprocessor

resolveSource

postprocess

beforeEmit

afterEmit

integrityHashes

Plugin options

test

entry

Simple syntax

Advanced syntax

import

filename

data

Entry as an array

Entry as an object

Entry as a path to templates

entryFilter

entryFilter as RegExp

entryFilter as Array<RegExp>

entryFilter as { includes: Array<RegExp>, excludes: Array<RegExp> }

entryFilter as callback

outputPath

filename

js

css

css.hot option

data

beforePreprocessor

preprocessor (callback or string) and preprocessorOptions

postprocess callback

beforeEmit callback

afterEmit callback

preload

Preload styles

Preload scripts

Preload images

Preload fonts

Preload tags order

minify

minifyOptions

`output.path`

`output.publicPath`

`output.filename`

`entry`

When using `callbacks`

When using `hooks`

`beforePreprocessor`

`preprocessor`

`resolveSource`

`postprocess`

`beforeEmit`

`afterEmit`

`integrityHashes`

`test`

`entry`

`import`

`filename`

`data`

`entryFilter`

`entryFilter` as `RegExp`

`entryFilter` as `Array<RegExp>`

`entryFilter` as `{ includes: Array<RegExp>, excludes: Array<RegExp> }`

`entryFilter` as `callback`

`outputPath`

`filename`

`js`

`css`

`css.hot` option

`data`

`beforePreprocessor`

`preprocessor` (callback or string) and `preprocessorOptions`

`postprocess` callback

`beforeEmit` callback

`afterEmit` callback

`preload`

`minify`

`minifyOptions`

`extractComments`

`integrity`

`integrityHashes` hook

`watchFiles`

`hotUpdate`

`verbose`

`loaderOptions`

`sources`

`filter` function

`root`

`context`

`beforePreprocessor`

`preprocessor`

`preprocessorOptions`

Options for `preprocessor: 'eta'` (default)

Options for `preprocessor: 'ejs'`

Options for `preprocessor: 'handlebars'`

Options for `preprocessor: 'tempura'`

Options for `preprocessor: 'nunjucks'`