Registry / web-framework / html-bundler-webpack-plugin

html-bundler-webpack-plugin

library4.23.0jsnpmunverified

The `html-bundler-webpack-plugin` is a Webpack plugin designed to streamline the creation of single-page or multi-page websites directly from HTML templates. Unlike `html-webpack-plugin` which primarily injects bundled assets, this plugin treats HTML files as entry points, resolving all linked assets (scripts, styles, images, fonts) within the HTML and CSS itself. It handles asset processing and ensures correct output URLs after Webpack's build. Key differentiators include built-in support for numerous template engines like Eta, EJS, Handlebars, Nunjucks, Pug, Tempura, TwigJS, LiquidJS, and Markdown out-of-the-box. It also simplifies asset resolution in CSS without requiring `resolve-url-loader`. The plugin is currently in a very active development state, with version 4.23.0 being the latest stable release, and frequent updates addressing features, fixes, and Webpack compatibility.

web-framework devops

npm install html-bundler-webpack-plugin

github ↗package ↗

INSTALL

IMPORT

SIG · HTML-BUNDLER-WEBPA

html-bundler-webpack-plugin

web-frameworkjavascriptv4.23.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

HtmlBundlerPlugin

✓ import { HtmlBundlerPlugin } from 'html-bundler-webpack-plugin';

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

The library primarily uses ES Modules and modern Node.js environments (>=18) are expected. While CJS might work in some contexts, ESM import is the recommended and type-safe approach.

This quickstart sets up a basic Webpack configuration to compile two HTML entry points (`index.html`, `about.html`), processing linked SCSS, JavaScript, and SVG/image assets. It demonstrates aliased paths and hashed output filenames.

import path from 'path'; import { fileURLToPath } from 'url'; import { HtmlBundlerPlugin } from 'html-bundler-webpack-plugin'; const __filename = fileURLToPath(import.meta.url); const __dirname = path.dirname(__filename); export default { mode: 'development', output: { path: path.join(__dirname, 'dist'), clean: true, }, resolve: { alias: { '@images': path.join(__dirname, 'src/images'), '@styles': path.join(__dirname, 'src/styles'), '@scripts': path.join(__dirname, 'src/scripts'), }, }, plugins: [ new HtmlBundlerPlugin({ entry: { index: './src/views/index.html', about: './src/views/about.html', }, js: { filename: 'js/[name].[contenthash:8].js', }, css: { filename: 'css/[name].[contenthash:8].css', }, }), ], module: { rules: [ { test: /\.(png|jpe?g|svg|ico)$/i, type: 'asset/resource', generator: { filename: 'img/[name].[hash:8][ext]', }, }, { test: /\.(scss|css)$/, use: ['css-loader', 'sass-loader'], }, { test: /\.ejs$/, loader: 'html-bundler-webpack-plugin/preprocessor/ejs', } ], }, }; // src/views/index.html // <!DOCTYPE html> // <html lang="en"> // <head> // <meta charset="UTF-8"> // <meta name="viewport" content="width=device-width, initial-scale=1.0"> // <title>Home</title> // <link href="@styles/main.scss" rel="stylesheet"> // </head> // <body> // <h1>Welcome to the Homepage</h1> // <img src="@images/logo.svg" alt="Logo"> // <script src="@scripts/main.js"></script> // </body> // </html> // src/scripts/main.js // console.log('Hello from main.js!'); // src/styles/main.scss // body { font-family: sans-serif; .logo { width: 100px; } }

Debug

Known issues

breakingVersion 4.0.0 introduced breaking changes, requiring Node.js 18+ and Webpack 5.81+. Custom plugins extending `HtmlBundlerPlugin` also need to adapt to `option` no longer being a static property.

fix

Ensure your Node.js version is >=18 and Webpack is >=5.81. If extending the plugin, update references from `MyPlugin.option` to `this.option` within the plugin instance methods.

affects: >=4.0.0

breakingWebpack versions >= 5.96.0 introduced undocumented breaking changes in `AssetGenerator` and `CodeGenerationResults` classes, which required specific adaptations in `html-bundler-webpack-plugin` v4.2.0. Older plugin versions will fail with Webpack 5.96+.

fix

Upgrade `html-bundler-webpack-plugin` to version 4.2.0 or higher if you are using Webpack 5.96.0 or newer.

affects: >=4.2.0

breakingIn v4.19.1, the default behavior for inlining SVG images changed. Previously, `<img src='icon.svg'>` would replace the `<img>` tag with the `<svg>` content. Now, by default, it inlines SVG as a base64-encoded data URL.

fix

To revert to the old behavior (replacing `<img>` with `<svg>` tag), set the `svg.inline.embed` option to `true` in the plugin configuration. For explicit base64 encoding or escaped URLs, use query parameters like `?inline=base64` or `?inline=escape`.

affects: >=4.19.1

breakingThe `PreloadFilter` type signature changed in v4.17.0, affecting custom filter functions.

fix

Review and update any custom `PreloadFilter` functions to align with the new type definition which now expects a function that returns `void | boolean` and receives an `asset` object with `sourceFiles` and `outputFile` properties.

affects: >=4.17.0

gotchaUsing Webpack's `splitChunks` optimization can lead to 'Can't resolve a CSS file in template' errors, as noted in v4.5.3 release logs.

fix

If encountering CSS resolution issues with `splitChunks`, review your Webpack `optimization.splitChunks` configuration. Consider adjusting `css.inline` or `css.filename` options, or temporarily disabling `splitChunks` for CSS to diagnose.

affects: >=4.5.3

gotchaWhen migrating from `html-webpack-plugin`, note that `html-bundler-webpack-plugin` treats HTML templates as entry points and handles asset resolution internally. This means fewer loaders/plugins might be needed compared to `html-webpack-plugin` setups.

fix

Refactor your Webpack configuration to leverage the built-in asset resolution and template engine support. Remove redundant loaders for HTML processing, CSS URL resolution (like `resolve-url-loader`), and script/style injection plugins.

affects: All

Errors

Common errors & fixes

Resolving of source files in the template file failed. File: src/pages/insects-gallery.ejs Error: The 'source' tag starting at XXXX position is missing the closing '>' char.

Despite the error message, the HTML syntax for tags like `<source>` is often correct; the plugin's parser might be misinterpreting complex or malformed HTML within templates.

fix

Carefully inspect the specified HTML template file at the given position. While the error mentions a missing `>`, it can also indicate other parsing issues. Ensure all tags are properly nested and self-closing tags are correctly formatted. Sometimes, simplifying complex HTML structures or ensuring valid HTML5 can resolve this.

Error: HtmlBundlerPlugin is not a constructor

This error typically occurs when attempting to `require` the plugin in a CommonJS context while the package might be primarily ESM, or when incorrectly importing a named export as a default export.

fix

Ensure you are using `import { HtmlBundlerPlugin } from 'html-bundler-webpack-plugin';` in an ESM-enabled Webpack configuration file (e.g., `webpack.config.mjs` or `webpack.config.js` with `type: module` in `package.json`). If you must use CommonJS, ensure your environment correctly transpiles ESM or the package provides a CJS entry point.

Plugin could not be registered at 'html-webpack-plugin-before-html-processing'. Hook was not found. BREAKING CHANGE: There need to exist a hook at 'this.hooks'.

This error points to a plugin compatibility issue, likely when an older version of `html-webpack-plugin` (or a plugin extending it) is used with a newer Webpack version, or vice-versa, due to changes in Webpack's plugin API hooks.

fix

Although this specific error message refers to `html-webpack-plugin`, the underlying cause (incompatible plugin hooks) can apply to any Webpack plugin. Ensure all Webpack-related packages, including `html-bundler-webpack-plugin` and any plugins that extend it, are compatible with your Webpack version. Update to the latest versions if possible.

Can't resolve 'file.css' in 'template.html'

This error indicates that the plugin cannot locate a CSS file referenced within an HTML template or imported into JavaScript, often due to incorrect paths, missing webpack aliases, or issues with asset processing rules.

fix

Verify the path to 'file.css' is correct relative to the HTML template or resolve `alias` configuration. Check your `module.rules` in `webpack.config.js` to ensure that CSS files are being correctly handled (e.g., `css-loader`, `sass-loader`) and that the output filename configuration for CSS (`css.filename`) is correctly set.

Upgrade

Version history

4.23.0latest on npm

Audit

Dependencies

webpackrequiredCore bundling engine for which this is a plugin.

ejsoptionalCommonly used template engine, required for EJS template processing.

handlebarsoptionalPopular template engine, required for Handlebars template processing.

nunjucksoptionalTemplating engine, required for Nunjucks template processing.

pugoptionalHigh-performance template engine, required for Pug template processing.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/webdiscus/html-bundler-webpack-plugin ↗

packagehttps://www.npmjs.com/package/html-bundler-webpack-plugin ↗