feat: add pipeline for many postrocesses

Author: webdiscus

CHANGELOG.md

@@ -1,5 +1,32 @@
 # Change log
 
+## 3.7.0 (2024-03-21)
+
+- feat: add the possibility to add many post processes. Next postprocess receives the result from previous.
+  So you can extend this plugin with additional default functionality.
+  ```js
+  class MyPlugin extends HtmlBundlerPlugin {
+    init(compiler) {
+      MyPlugin.option.addProcess('postprocess', (content) => {
+        // TODO: modify the generated HTML content
+        return content;
+      });
+    }
+  }
+  
+  module.exports = {
+    plugins: [
+      new MyPlugin({
+        entry: {
+          index: './src/index.html',
+        },
+      }),
+    ],
+  };
+  ```
+  This feature is used in the [pug-plugin](https://github.com/webdiscus/pug-plugin) for pretty formatting generated HTML.\
+  See an example in the [test case](https://github.com/webdiscus/html-bundler-webpack-plugin/tree/master/test/cases/option-postprocess-pipe).
+
 ## 3.6.5 (2024-03-19)
 
 - fix: define the unique instance name for the plugin as `HtmlBundlerPlugin` instead of `Plugin`

README.md

@@ -230,11 +230,26 @@ If you have discovered a bug or have a feature suggestion, feel free to create a
 
 For full release notes see the [changelog](https://github.com/webdiscus/html-bundler-webpack-plugin/blob/master/CHANGELOG.md).
 
-> **Warning**\
-> **Limitation**
->
-> The current version works stable with `cache.type` as `'memory'` (Webpack's default setting).\
-> Support for the `'filesystem'` cache type is experimental and under development.
+## ⚠️ Limitations
+
+### Cache type
+
+The current version works stable with `cache.type` as `'memory'` (Webpack's default setting).\
+Support for the `'filesystem'` cache type is experimental.
+
+### Multiple config files
+
+The multiple config files are not supported, because in some special use cases the Webpack API works not properly (all previous configurations are overridden by the latest configuration).
+
+Instead of this:
+```
+npx webpack -c app1.config.js app2.config.js
+```
+you can use following:
+```
+npx webpack -c app1.config.js
+npx webpack -c app2.config.js
+```
 
 ---
 
@@ -524,6 +539,7 @@ See [boilerplate](https://github.com/webdiscus/webpack-html-scss-boilerplate)
 2. [Problems & Solutions](#solutions)
    - [Automatic resolving of file extensions](#solutions-resolve-extensions)
    - [How to use `@import url()` in CSS](#solutions-import-url-in-css)
+   - [How to disable resolving in commented out tag](#solutions-disable-resolving-in-commented-out-tag)
 3. <a id="demo-sites" name="demo-sites"></a> 
    Demo sites
    - Multiple page e-shop template (`Handlebars`) [demo](https://alpine-html-bootstrap.vercel.app/) | [source](https://github.com/webdiscus/demo-shop-template-bundler-plugin)
@@ -6021,6 +6037,25 @@ The plugin does not support handling of `@import url()` in CSS. Imported url wil
 > 
 > The `*.css` files imported in CSS are not handled, therefore these files must be manually copied to the `dist/` folder using the `copy-webpack-plugin`.
 
+#### [↑ back to contents](#contents)
+
+<a id="solutions-disable-resolving-in-commented-out-tag" name="solutions-disable-resolving-in-commented-out-tag"></a>
+
+## How to disable resolving in commented out tag
+
+In [default attributes](#default-attributes), files will be resolved automatically, regardless of whether the tag is commented out or not.
+This is not a bug, it is a feature for very fast attribute parsing.
+
+If you commented out a tag and don't want to resolve files in the tag's [attributes](#default-attributes), rename the attribute.
+For example: `href` -> `x-href` or `src` -> `x-src`.
+
+```html
+<!-- <link x-href="./styles.css" rel="stylesheet /> -->
+<!-- <script x-src="./main.js" defer="defer"></script> -->
+<!-- <img x-src="./image.png"> -->
+```
+
+
 #### [↑ back to contents](#contents)
 
 ---

package.json

@@ -1,6 +1,6 @@
 {
   "name": "html-bundler-webpack-plugin",
-  "version": "3.6.5",
+  "version": "3.7.0",
   "description": "HTML bundler plugin for webpack handles a template as an entry point, extracts CSS and JS from their sources referenced in HTML, supports template engines like Eta, EJS, Handlebars, Nunjucks.",
   "keywords": [
     "html",

src/Plugin/Collection.js

@@ -1013,7 +1013,6 @@ class Collection {
       // 9. beforeEmit hook allows plugins to change the html after chunks and inlined assets are injected
       promise = promise.then((content) => hooks.beforeEmit.promise(content, compileEntry) || content);
 
-      // TODO: add in readme: use callbacks for debugging or small features
       // 10. beforeEmit callback
       if (Option.hasBeforeEmit()) {
         promise = promise.then((content) => Option.beforeEmit(content, compileEntry, compilation) || content);

src/Plugin/Option.js

@@ -15,6 +15,7 @@ class Option {
   static cacheable = false;
   static context = '';
   static testEntry = null;
+
   static js = {
     test: /\.(js|ts|jsx|tsx|mjs|cjs|mts|cts)$/,
     enabled: true,
@@ -23,6 +24,7 @@ class Option {
     outputPath: undefined,
     inline: false,
   };
+
   static css = {
     test: /\.(css|scss|sass|less|styl)$/,
     enabled: true,
@@ -32,6 +34,14 @@ class Option {
     inline: false,
   };
 
+  /**
+   * The pipeline of processes.
+   * The result of one will be passed into next.
+   *
+   * @type {Map<string, Array<Function>>}
+   */
+  static #process = new Map();
+
   /**
    * Initialize plugin options.
    *
@@ -50,6 +60,9 @@ class Option {
 
     const loaderOptions = this.options.loaderOptions;
 
+    // remove cached data from previous webpack running
+    this.#process.clear();
+
     // add reference for the preprocessor option into the plugin options
     if (loaderOptions && loaderOptions.preprocessor != null) {
       options.preprocessor = loaderOptions.preprocessor;
@@ -63,6 +76,10 @@ class Option {
     if (!isFunction(options.beforeEmit)) this.options.beforeEmit = null;
     if (!isFunction(options.afterEmit)) this.options.afterEmit = null;
 
+    if (this.options.postprocess != null) {
+      this.addProcess('postprocess', this.options.postprocess);
+    }
+
     if (!options.watchFiles) this.options.watchFiles = {};
     this.options.hotUpdate = this.options.hotUpdate === true;
   }
@@ -437,7 +454,7 @@ class Option {
   }
 
   static hasPostprocess() {
-    return this.options.postprocess != null;
+    return this.#process.has('postprocess');
   }
 
   static hasBeforeEmit() {
@@ -677,6 +694,46 @@ class Option {
     }
   }
 
+  /**
+   * Add the process to pipeline.
+   *
+   * @param {string} name The name of process. Currently supported only `postprocess` pipeline.
+   * @param {Function} fn The process function.
+   */
+  static addProcess(name, fn) {
+    let processes = this.#process.get(name);
+
+    if (!processes) {
+      processes = [];
+      this.#process.set(name, processes);
+    }
+
+    processes.push(fn);
+  }
+
+  /**
+   * @param {string} name The name of a process.
+   * @param {Array<*>} args The arguments of a process.
+   * @return {*|null} The result of passed through all processes.
+   */
+  static #runProcesses(name, args) {
+    let processPipe = this.#process.get(name);
+    let i = 0;
+    let result;
+
+    for (; i < processPipe.length; i++) {
+      const postprocess = processPipe[i];
+      result = postprocess.apply(null, args);
+
+      // the result will be pipelined in the next function as the first argument
+      if (result != null) {
+        args[0] = result;
+      }
+    }
+
+    return result;
+  }
+
   /**
    * Called after js template is compiled into html string.
    *
@@ -688,7 +745,7 @@ class Option {
    */
   static postprocess(content, info, compilation) {
     try {
-      return this.options.postprocess(content, info, compilation);
+      return this.#runProcesses('postprocess', [content, info, compilation]);
     } catch (error) {
       postprocessException(error, info);
     }
@@ -697,8 +754,6 @@ class Option {
   /**
    * Called after processing all plugins, before emit.
    *
-   * TODO: test not yet documented experimental feature
-   *
    * @param {string} content
    * @param {CompileEntry} entry
    * @param {Compilation} compilation

src/index.js

@@ -42,7 +42,7 @@ class HtmlBundlerPlugin extends AssetCompiler {
    * @param {Compiler} compiler The instance of the webpack compilation.
    */
   init(compiler) {
-    // TODO: do some thing in an extended plugin
+    // do some thing in an extended plugin
   }
 }
 

test/cases/option-postprocess-pipe/expected/index.html

@@ -0,0 +1,10 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Test</title>
+</head>
+<body>
+  <h1>Hello World!</h1>
+  <p>The new replaced content.</p>
+</body>
+</html>

test/cases/option-postprocess-pipe/src/index.html

@@ -0,0 +1,10 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Test</title>
+</head>
+<body>
+  <h1>Hello World!</h1>
+  <p>REPLACE ME FIRST</p>
+</body>
+</html>

test/cases/option-postprocess-pipe/src/main.js

@@ -0,0 +1 @@
+console.log('>> main');

test/cases/option-postprocess-pipe/src/style.scss

@@ -0,0 +1,3 @@
+body {
+  color: red;
+}