{"id":15641,"library":"html-bundler-webpack-plugin","title":"HTML Bundler Webpack Plugin","description":"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.","status":"active","version":"4.23.0","language":"javascript","source_language":"en","source_url":"https://github.com/webdiscus/html-bundler-webpack-plugin","tags":["javascript","html","bundler","webpack","plugin","loader","template","ejs","hbs","typescript"],"install":[{"cmd":"npm install html-bundler-webpack-plugin","lang":"bash","label":"npm"},{"cmd":"yarn add html-bundler-webpack-plugin","lang":"bash","label":"yarn"},{"cmd":"pnpm add html-bundler-webpack-plugin","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core bundling engine for which this is a plugin.","package":"webpack","optional":false},{"reason":"Commonly used template engine, required for EJS template processing.","package":"ejs","optional":true},{"reason":"Popular template engine, required for Handlebars template processing.","package":"handlebars","optional":true},{"reason":"Templating engine, required for Nunjucks template processing.","package":"nunjucks","optional":true},{"reason":"High-performance template engine, required for Pug template processing.","package":"pug","optional":true}],"imports":[{"note":"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.","wrong":"const HtmlBundlerPlugin = require('html-bundler-webpack-plugin');","symbol":"HtmlBundlerPlugin","correct":"import { HtmlBundlerPlugin } from 'html-bundler-webpack-plugin';"}],"quickstart":{"code":"import path from 'path';\nimport { fileURLToPath } from 'url';\nimport { HtmlBundlerPlugin } from 'html-bundler-webpack-plugin';\n\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = path.dirname(__filename);\n\nexport default {\n mode: 'development',\n output: {\n path: path.join(__dirname, 'dist'),\n clean: true,\n },\n resolve: {\n alias: {\n '@images': path.join(__dirname, 'src/images'),\n '@styles': path.join(__dirname, 'src/styles'),\n '@scripts': path.join(__dirname, 'src/scripts'),\n },\n },\n plugins: [\n new HtmlBundlerPlugin({\n entry: {\n index: './src/views/index.html',\n about: './src/views/about.html',\n },\n js: {\n filename: 'js/[name].[contenthash:8].js',\n },\n css: {\n filename: 'css/[name].[contenthash:8].css',\n },\n }),\n ],\n module: {\n rules: [\n {\n test: /\\.(png|jpe?g|svg|ico)$/i,\n type: 'asset/resource',\n generator: {\n filename: 'img/[name].[hash:8][ext]',\n },\n },\n {\n test: /\\.(scss|css)$/,\n use: ['css-loader', 'sass-loader'],\n },\n {\n test: /\\.ejs$/,\n loader: 'html-bundler-webpack-plugin/preprocessor/ejs',\n }\n ],\n },\n};\n\n// src/views/index.html\n// \n// \n// \n// \n// \n// Home\n// \n// \n// \n//

Welcome to the Homepage

\n// \"Logo\"\n// \n// \n// \n\n// src/scripts/main.js\n// console.log('Hello from main.js!');\n\n// src/styles/main.scss\n// body { font-family: sans-serif; .logo { width: 100px; } }","lang":"javascript","description":"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."},"warnings":[{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Upgrade `html-bundler-webpack-plugin` to version 4.2.0 or higher if you are using Webpack 5.96.0 or newer.","message":"Webpack 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+.","severity":"breaking","affected_versions":">=4.2.0"},{"fix":"To revert to the old behavior (replacing `` with `` 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`.","message":"In v4.19.1, the default behavior for inlining SVG images changed. Previously, `` would replace the `` tag with the `` content. Now, by default, it inlines SVG as a base64-encoded data URL.","severity":"breaking","affected_versions":">=4.19.1"},{"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.","message":"The `PreloadFilter` type signature changed in v4.17.0, affecting custom filter functions.","severity":"breaking","affected_versions":">=4.17.0"},{"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.","message":"Using Webpack's `splitChunks` optimization can lead to 'Can't resolve a CSS file in template' errors, as noted in v4.5.3 release logs.","severity":"gotcha","affected_versions":">=4.5.3"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"Despite the error message, the HTML syntax for tags like `` is often correct; the plugin's parser might be misinterpreting complex or malformed HTML within templates.","error":"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."},{"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.","cause":"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.","error":"Error: HtmlBundlerPlugin is not a constructor"},{"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.","cause":"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.","error":"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'."},{"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.","cause":"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.","error":"Can't resolve 'file.css' in 'template.html'"}],"ecosystem":"npm"}