HTML Bundler Webpack Plugin

Common errors

• 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.

  cause 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

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

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

  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.
  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.

Warnings

• breaking 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.
  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.
• breaking 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+.
  Fix: Upgrade `html-bundler-webpack-plugin` to version 4.2.0 or higher if you are using Webpack 5.96.0 or newer.
• breaking In 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`.
• breaking The `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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install html-bundler-webpack-plugin npm
• yarn add html-bundler-webpack-plugin yarn
• pnpm add html-bundler-webpack-plugin pnpm

Imports

• HtmlBundlerPlugin
  wrong:

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

  correct:

  import { HtmlBundlerPlugin } from '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.

Quickstart

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; } }