feat: add support the HMR for styles imported in JavaScript files

Author: webdiscus

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Change log
 
+## 4.5.0 (2024-11-25)
+
+- feat: add limited support the HMR for styles imported in JavaScript files
+- feat: add new `css.hot` option to enable HMR for styles
+
 ## 4.4.3 (2024-11-23)
 
 - fix: issue by inline a style when in the tag used single quotes for attribute

README.md

@@ -17,9 +17,9 @@ Advanced alternative to [html-webpack-plugin](https://github.com/jantimon/html-w
 
 ---
 
-<div align="center">
+<h4 align="center">
 📋 <a href="#contents">Table of Contents</a> 🚀 <a href="#install">Install and Quick Start</a> 🖼 <a href="#usage-examples">Usage examples</a> 🔆 <a href="#whats-new">What's New</a>
-</div>
+</h4>
 
 <!--
 #### 📋 [Table of Contents](#contents) 🚀 [Install and Quick Start](#install) 🖼 [Usage examples](#usage-examples)
@@ -44,6 +44,7 @@ Advanced alternative to [html-webpack-plugin](https://github.com/jantimon/html-w
   - `<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](#recipe-inline-js), [CSS](#recipe-inline-css) and [Images](#recipe-inline-image) into HTML. See [how to inline all resources](#recipe-inline-all-assets-to-html) into single HTML file.
+- [HMR for CSS](#option-css-hot) - update CSS in browser without a full reload.
 - Recompiles the template after changes in the [data file](#option-entry-data) assigned to the entry page as a JSON or JS filename.
 - Generates the [preload](#option-preload) tags for fonts, images, video, scripts, styles.
 - Generates the [integrity](#option-integrity) attribute in the `link` and `script` tags.
@@ -208,6 +209,7 @@ If you have discovered a bug or have a feature suggestion, feel free to create a
 
 ## 🔆 What's New in v4
 
+- **NEW** added supports the [HMR for CSS](#option-css-hot) (since `v4.5.0`).
 - **NEW** added supports the [multiple configurations](https://webpack.js.org/configuration/configuration-types/#exporting-multiple-configurations).
 - **SUPPORTS** Webpack version `5.96+` (since `v4.2.0`).
 - **SUPPORTS** Webpack version `5.81+` (since `v4.0.0`).
@@ -1964,6 +1966,7 @@ type CssOptions = {
   chunkFilename?: FilenameTemplate;
   outputPath?: string;
   inline?: 'auto' | boolean;
+  hot?: boolean;
 };
 ```
 
@@ -1976,19 +1979,22 @@ Default properties:
   chunkFilename: '[name].css',
   outputPath: null,
   inline: false,
+  hot: false,
 }
 ```
 
 - `test` - an RegEpx to process all source styles that pass test assertion
 - `filename` - an output filename of extracted CSS. Details see by [filename option](#option-filename).
 - `chunkFilename` - an output filename of non-initial chunk files, e.g., a style file imported in JavaScript.
 - `outputPath` - an output path of extracted CSS. Details see by [outputPath option](#option-outputpath).
-- `inline` - inlines extracted CSS into HTML, available values:
+- `inline` - inject CSS into into HTML at render time, available values:
   - `false` - stores CSS in an output file (**defaults**)
   - `true` - adds CSS to the DOM by injecting a `<style>` tag
   - `'auto'` - in `development` mode - adds to DOM, in `production` mode - stores as a file
+- `hot` - inject CSS into the DOM at runtime and enable HMR (hot update CSS without a full reload),\
+  similar to how it works in [style-loader](https://github.com/webpack-contrib/style-loader).
 
-All source style files specified in `<link href="..." rel="stylesheet">` are automatically resolved,  
+All source style files specified in `<link href="..." rel="stylesheet">` are automatically resolved,
 and CSS will be extracted to output file. The source filename will be replaced with the output filename.
 
 For example:
@@ -2022,13 +2028,53 @@ The `[name]` is the base filename of a loaded style.
 For example, if source file is `style.scss`, then output filename will be `css/style.1234abcd.css`.\
 If you want to have a different output filename, you can use the `filename` options as the [function](https://webpack.js.org/configuration/output/#outputfilename).
 
+<a id="option-css-hot" name="option-css-hot"></a>
+
+#### `css.hot` option
+
+> ⚠️ Limitation
+> 
+> - HMR works only for styles imported in JavaScript files. Doesn't works for styles defined directly in HTML via `link` tag.
+> - Hot update without a full reload works only for styles imported in a last JavaScript file.\
+>   If you have many JS files defined in HTML, where are imported styles, and change a style file imported in the first JS file,
+>   then changes will not be detected in HMR module. You should reload the browser manually.
+>   This behaviour is a BUG in Webpack. The [style-loader](https://github.com/webpack-contrib/style-loader) has exactly same limitation. 
+>
+
+If you use the [Live Reload](#setup-live-reload) configuration, then be sure to exclude the style files (CSS/SCSS) from watching,
+otherwise after changes a style file, a page will be full reloaded.
+
+> ℹ️ Note
+> 
+> If `devServer` is configured for HRM with styles, then after changing the styles defined in HTML, `Live Reload` will not work for them.
+> You should then reload the browser self.
+
+Configuration of `devServer` to enable HMR:
+
+```js
+devServer: {
+  static: {
+    directory: path.join(__dirname, 'dist'),
+  },
+  watchFiles: {
+    paths: ['src/**/*.(html|eta)'], // <= exclude *.s?css from watching
+    options: {
+      usePolling: true,
+    },
+  },
+},
+``` 
+
+**💡 Tip**: to enable HMR for all style files without a full reload, import all those styles in one JS file.
+
+
 > ⚠️ **Warning**
 >
 > Don't use `mini-css-extract-plugin` because the bundler plugin extracts CSS much faster than other plugins.
 >
 > Don't use `resolve-url-loader` because the bundler plugin resolves all URLs in CSS, including assets from node modules.
 >
-> Don't use `style-loader` because the bundler plugin can auto inline CSS.
+> Don't use `style-loader` because the bundler plugin can auto inline CSS and HMR.
 
 #### [↑ back to contents](#contents)
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "html-bundler-webpack-plugin",
-  "version": "4.4.3",
+  "version": "4.5.0",
   "description": "HTML Bundler Plugin for Webpack renders HTML templates containing source files of scripts, styles, images. Supports template engines: Eta, EJS, Handlebars, Nunjucks, Pug, TwigJS. Alternative to html-webpack-plugin.",
   "keywords": [
     "html",
@@ -25,7 +25,7 @@
     "javascript",
     "css",
     "scss",
-    "style",
+    "style-loader",
     "html-webpack-plugin"
   ],
   "license": "ISC",

src/Loader/Hmr/hot-update.js

@@ -1,2 +1,2 @@
 // To enable live reload, just add an empty JS file in HTML.
-// Webpack automatically inserts the hot update code into this file.
+// Webpack automatically inserts the runtime code into this file.

src/Loader/cssLoader.js

@@ -29,6 +29,7 @@ const pitchLoader = async function (remaining) {
   const pluginCompiler = loaderContext._compilation.compiler;
   const pluginContext = PluginService.getPluginContext(pluginCompiler);
   const collection = pluginContext.collection;
+  const isHmr = pluginContext.pluginOption.isCssHot();
 
   // TODO: find the module from this._compilation, because this._module is deprecated
   const { resource, resourcePath, _module: module } = this;
@@ -49,8 +50,11 @@ const pitchLoader = async function (remaining) {
 
   // defaults, the css-loader option `esModule` is `true`
   const esModule = result.default != null;
+  const cssSource = esModule ? result.default : result;
   let styles;
 
+  collection.setImportStyleEsModule(esModule);
+
   if (esModule) {
     const exports = Object.keys(result).filter((key) => key !== 'default');
 
@@ -64,15 +68,62 @@ const pitchLoader = async function (remaining) {
     styles = result.locals;
   }
 
-  module._cssSource = esModule ? result.default : result;
-  collection.setImportStyleEsModule(esModule);
+  if (!isHmr) {
+    module._cssSource = cssSource;
+  }
 
   // support for lazy load CSS in JavaScript, see the test js-import-css-lazy-url
   if (isUrl) {
-    return exportComment + module._cssSource;
+    return exportComment + cssSource;
+  }
+
+  let hmrCode = '';
+
+  if (isHmr) {
+    const css = result.default.toString().replaceAll('\n', '');
+
+    hmrCode = `
+const css = \`${css}\`;
+const isDocument = typeof document !== 'undefined';
+
+if (!isDocument) {
+  console.log('CSS HMR does not work!');
+}
+
+if (isDocument && module.hot) {
+  module.hot.accept(undefined, function () {
+    // required to avoid full reload
+  });
+  
+  const key = '__bundlerCssHmr';
+  
+  document[key] = document[key] || { idx: 1, styleIds: new Map() };
+  const hmr = document[key];
+  const moduleId = module.id;
+
+  let styleId = hmr.styleIds.get(moduleId);
+  let styleElm;
+
+  if (styleId) {
+    styleElm = document.getElementById(styleId);
+  } else {
+    styleId = 'hot-update-style-' + hmr.idx++;
+    styleElm = document.createElement('style');
+    styleElm.setAttribute('id', styleId);
+    document.head.appendChild(styleElm);
+    hmr.styleIds.set(moduleId, styleId);
+  }
+
+  if (styleElm) {
+     styleElm.innerText = css;
+  }
+}
+`;
   }
 
-  return styles ? (esModule ? 'export default' : 'module.exports = ') + JSON.stringify(styles) : exportComment;
+  return styles
+    ? (esModule ? 'export default' : 'module.exports = ') + JSON.stringify(styles)
+    : exportComment + hmrCode;
 };
 
 module.exports = loader;

src/Plugin/AssetCompiler.js

@@ -988,7 +988,7 @@ class AssetCompiler {
     }
 
     // 2. renders styles imported in JavaScript
-    if (this.collection.hasImportedStyle(this.currentEntryPoint?.id)) {
+    if (!this.option.isCssHot() && this.collection.hasImportedStyle(this.currentEntryPoint?.id)) {
       this.renderImportStyles(result, { chunk });
     }
   }
@@ -1429,6 +1429,8 @@ class AssetCompiler {
       resource,
       filename: assetFile,
     };
+    const isStyle = type === 'style';
+
     this.resolver.setContext(this.currentEntryPoint, issuer);
 
     const vmScript = new VMScript({
@@ -1441,11 +1443,11 @@ class AssetCompiler {
 
     // the css-loader defaults generate ESM code, which must be transformed into CommonJS to compile the code
     // the template loader generates CommonJS code, no need to transform
-    const esModule = type === 'style' || loaderOptions.esModule === true;
+    const esModule = isStyle || loaderOptions.esModule === true;
     let result = vmScript.exec(source.source(), { filename: sourceFile, esModule });
 
-    if (type === 'style') {
-      result = this.cssExtractModule.apply(result);
+    if (isStyle) {
+      return this.cssExtractModule.apply(result);
     }
 
     return result;

src/Plugin/Messages/Exception.js

@@ -74,10 +74,10 @@ const optionPreloadAsException = (config, type, availableTypes) => {
  * @param {string} file The unresolved file can be absolute or relative.
  * @param {string} issuer The absolute issuer file of unresolved file.
  * @param {string} rootContext The absolute path to project files.
- * @param {object} pluginOptions The instance of the pluginOptions.
+ * @param {object} pluginOption The instance of the plugin Option.
  * @throws {Error}
  */
-const resolveException = (file, issuer, rootContext, pluginOptions) => {
+const resolveException = (file, issuer, rootContext, pluginOption) => {
   let isExistsFile = true;
   issuer = path.relative(rootContext, issuer);
 
@@ -104,7 +104,7 @@ const resolveException = (file, issuer, rootContext, pluginOptions) => {
     },
   ],
 },`;
-  } else if (pluginOptions.isStyle(file) && hasSplitChunksCacheGroups(pluginOptions.webpackOptions)) {
+  } else if (pluginOption.isStyle(file) && hasSplitChunksCacheGroups(pluginOption.webpackOptions)) {
     message += `\n
 ${whiteBright.bgGreen` Tip `} 
 Add the ${white`'splitChunks.cacheGroups.{cacheGroup}.test'`} option as a RegExp to each cache group to split only script files, excluding styles.

src/Plugin/Option.js

@@ -17,6 +17,7 @@ class Option {
   context = '';
   testEntry = null;
   compiler = null;
+  devServerHot = false;
 
   js = {
     test: /\.(js|ts|jsx|tsx|mjs|cjs|mts|cts)$/,
@@ -34,6 +35,7 @@ class Option {
     chunkFilename: undefined,
     outputPath: undefined,
     inline: false,
+    hot: false,
   };
 
   #entryLibrary = {
@@ -128,6 +130,7 @@ class Option {
 
     css.enabled = this.toBool(css.enabled, true, this.css.enabled);
     css.inline = this.toBool(css.inline, false, this.css.inline);
+
     if (!css.outputPath) css.outputPath = options.output.path;
 
     if (!css.chunkFilename) {
@@ -231,6 +234,13 @@ class Option {
 
     this.initEntry(this.loaderPath);
     this.enableLibraryType();
+
+    if (options.devServer) {
+      // default value of the `hot` is `true`
+      // https://webpack.js.org/configuration/dev-server/#devserverhot
+      const hot = options.devServer?.hot;
+      this.devServerHot = (hot == null || hot === true || hot === 'only') && !this.isProduction();
+    }
   }
 
   /**
@@ -319,6 +329,24 @@ class Option {
     return this.productionMode;
   }
 
+  /**
+   * Returns the value of the `devServer.hot` webpack option.
+   * @return {boolean}
+   */
+  isDevServerHot() {
+    return this.devServerHot;
+  }
+
+  /**
+   * Whether HMR for CSS is available.
+   *
+   * @return {boolean}
+   */
+
+  isCssHot() {
+    return this.options.css.hot && this.devServerHot;
+  }
+
   /**
    * @return {boolean}
    */

test/manual/watch-css-hmr-import-multiple-js/package.json

@@ -0,0 +1,10 @@
+{
+  "scripts": {
+    "start": "webpack serve --mode development",
+    "watch": "webpack watch --mode development",
+    "build": "webpack --mode=production --progress"
+  },
+  "devDependencies": {
+    "html-bundler-webpack-plugin": "file:../../.."
+  }
+}

test/manual/watch-css-hmr-import-multiple-js/src/app.js

@@ -0,0 +1,7 @@
+import timer from './timer.js';
+
+import './timer.css';
+//import './style-a.css';
+//import './style-b.css';
+
+timer('#timer');