HTML Bundler Plugin for Webpack
_{All-in-one Web Bundler}

This plugin is all you need to generate a complete single- or multi-page website from your source assets.

The plugin automates the processing of source files such as JS/TS, SCSS, images and other assets referenced in an HTML or template file. This plugin will generate an HTML file containing all the necessary links to JS, CSS, images and other resources.

Why use the HTML Bundler Plugin?

This plugin is a powerful alternative to html-webpack-plugin and a replacement for many plugins and loaders.

The HTML Bundler Plugin works a bit differently than html-webpack-plugin. It doesn't just inject JavaScript and CSS into an HTML. Instead, it resolves all the source files of the assets referenced directly in the template and ensures the generated HTML contains the correct output URLs of resources after Webpack processes them. Additionally, CSS extracted from styles imported in JS can be injected into HTML as a <link> tag or as an inlined CSS.

📋 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.
Automatically processes templates found in the entry directory.
Build-in support for template engines: Eta, EJS, Handlebars, Nunjucks, Pug, Tempura, TwigJS, LiquidJS.
Build-in support for Markdown *.md files in templates, see Markdown demo in browser.
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 generated HTML.
Inlines JS, CSS and Images into HTML. See how to inline all resources into single HTML file.
Supports the HMR for CSS to update CSS in browser without a full reload.
Watches for changes in the data file linked to the template in the plugin option.
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 custom plugins using the provided 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({
      // specify the entry points for HTML pages (or a template)
      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!

↑ top | ↓ contents

⚙️ How the plugin works

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 you can include Markdown *.md files in your HTML template (since v4.6.0).
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.

↑ top | ↓ contents

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.

For splitChunks see How to configure splitChunks.

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

↑ top

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 template)
    - data as object (pass data in the template as an object)
    - data as JSON file (load data from JSON file)
    - data as JS file (dynamically load data from JS where can be used DB)
- 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 (resolving asset references in a specific tag attribute)
  - filter (allow fine-tuning to resolve specific cases)
- 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
- Using Markdown *.md files in templates View in browser | source

Name		Name	Last commit message	Last commit date
Latest commit History 249 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

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

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

HTML Bundler Plugin for Webpack All-in-one Web Bundler

Why use the HTML Bundler Plugin?

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

💡 Highlights

HTML template as entry point

❤️ Sponsors & Patrons

↑ top | ↓ contents

⚙️ How the plugin works

❓Question / Feature Request / Bug

📚 Read it

🔆 What's New in v4

🔆 What's New in v3

🔆 What's New in v2

⚠️ Limitations

Cache type

↑ top | ↓ contents

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

HTML Bundler Plugin for Webpack
_{All-in-one Web Bundler}

`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'`