feat: add the filter for the preload option

Author: webdiscus

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 4.14.0 (2025-01-19)
+
+- feat: add the `filter` for the `preload` option
+
 ## 4.13.0 (2025-01-18)
 
 - feat: add support for preloading of dynamic imported modules, #138

README.md

@@ -1660,16 +1660,16 @@ new HtmlBundlerPlugin({
 
 ### `entryFilter`
 
-Filter to process only matching template files.
+The filter to process only matching template files.
 This option works only if the [entry](#option-entry-path) option is a path.
 
 Type:
 ```ts
-type entryFilter = 
+type AdvancedFilter = 
   | RegExp
   | Array<RegExp>
   | { includes?: Array<RegExp>; excludes?: Array<RegExp> }
-  | ((file: string) => void | false);
+  | ((file: string) => void | true | false);
 ```
 
 Default value:
@@ -2501,20 +2501,30 @@ Type:
 ```ts
 type Preload = Array<{
   test: RegExp;
+  filter?: AdvancedFilter;
   as?: string;
   rel?: string;
   type?: string;
   attributes?: { [attributeName: string]: string | boolean };
 }>;
 ```
 
+```ts
+type AdvancedFilter =
+  | RegExp
+  | Array<RegExp>
+  | { includes?: Array<RegExp>; excludes?: Array<RegExp> }
+  | ((value: string) => void | true | false);
+```
+
 Default: `null`
 
 Generates and injects preload tags `<link rel="preload">` in the head before all `link` or `script` tags for all matching source assets resolved in templates and styles.
 
 The descriptions of the properties:
 
 - `test` - an RegEpx to match source asset files.
+- `filter` - an advanced filter to preload only matched output asset files.
 - `as` - a content type, one of `audio` `document` `embed` `font` `image` `object` `script` `style` `track` `video` `worker`
 - `rel` - a value indicates how to load a resource, one of `preload` `prefetch` , defaults `preload`
 - `type` - a [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types) of the content.\
@@ -2555,6 +2565,93 @@ For example:
 },
 ```
 
+<a id="option-preload-filter" name="option-preload-filter"></a>
+
+#### `filter` option
+
+By default, all files matching the `test` option will be preloaded. 
+You can use the `filter` to preload specific files individually.
+
+The `AdvancedFilter` type provides a versatile way to define filtering logic, 
+from simple patterns to complex inclusion and exclusion criteria. 
+
+Here's are supported filter formats:
+
+- `RegExp`\
+   The filter matches a value if it satisfies this single regular expression.\
+   Works the same as `{ includes: [RegExp,] }`.\
+   For example:
+   ```js
+   filter: /vendor/, // preload files containing the `vendor` string only
+   ```
+
+- `Array<RegExp>`\
+  Matches a value if it satisfies **at least one** of the regular expressions in the array.\
+  Works the same as `{ includes: [RegExp1, RegExp2, ...] }`.\
+  For example:
+  ```js
+  filter: [/vendor1/, /vendor2/,], // preload files containing the `vendor1` or `vendor2`
+  ```
+
+- `{ includes?: Array<RegExp>; excludes?: Array<RegExp> }`\
+  An object with optional `includes` and `excludes` arrays of regular expressions.\
+  For more advanced filtering where inclusion and exclusion criteria need to be combined:
+  - `includes`: Matches values that satisfy **at least one** of the regular expressions in the array.
+  - `excludes`: Rejects values that satisfy **at least one** of the regular expressions in the array.
+  - For `includes` and `excludes`, the logic is AND: a value must match the `includes` patterns and **not match** the `excludes` patterns.
+
+  For example:
+  ```js
+  filter: {
+    includes: [/include-this/,],
+    excludes: [/exclude-this/,],
+  }
+  ```
+- `(value: string) => void | false`\
+  Custom logic provides maximum flexibility for filtering that cannot be expressed with regular expressions.\
+  A custom filter function takes an output asset file as input and decides whether it matches based on the return value:
+  - Returns `void` (`undefined`) or `true` if the value passes the filter.
+  - Returns `false` if the value fails the filter.
+
+For example, preload all JS files except dynamically imported (async chunks).
+
+There is the _app.js_:
+
+```js
+// specify the name of an individual chunk to exclude from preloading
+import(
+ /* webpackChunkName: "moduleA.asyncChunk" */
+ './moduleA',
+);
+
+import('./moduleB'); // other asyncChunk which should be preloaded
+import './moduleC'; // normal module
+```
+
+Use the `filter` preload option to exclude files:
+```js
+preload: [
+  {
+    test: /\.(js|ts)$/,
+    filter: {
+      excludes: [/asyncChunk/],
+    },
+    as: 'script',
+  },
+],
+```
+
+The same effect using the `filter` function:
+```js
+preload: [
+  {
+    test: /\.(js|ts)$/,
+    filter: (assetFile) => !/asyncChunk/.test(assetFile),
+    as: 'script',
+  },
+],
+```
+
 #### Preload styles
 
 ```js
@@ -2646,6 +2743,7 @@ preload: [
 > 
 > See [font preload](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/preload#what_types_of_content_can_be_preloaded).
 
+
 #### Preload tags order
 
 The generated preload tags are grouped by content type and sorted in the order of the specified `preload` options.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "html-bundler-webpack-plugin",
-  "version": "4.13.0",
+  "version": "4.14.0",
   "description": "Generates complete single-page or multi-page website from source assets. Build-in support for Markdown, Eta, EJS, Handlebars, Nunjucks, Pug. Alternative to html-webpack-plugin.",
   "keywords": [
     "html",

src/Common/FileUtils.js

@@ -116,9 +116,9 @@ const readDirRecursiveSync = (dir, { fs, includes = [], excludes = [] }) => {
     for (const file of entries) {
       const current = path.join(dir, file.name);
 
-      if (noExcludes || !excludes.find((regex) => regex.test(current))) {
+      if (noExcludes || !excludes.some((regex) => regex.test(current))) {
         if (file.isDirectory()) result.push(...readDir(current));
-        else if (noIncludes || includes.find((regex) => regex.test(current))) result.push(current);
+        else if (noIncludes || includes.some((regex) => regex.test(current))) result.push(current);
       }
     }
 

src/Plugin/AssetEntry.js

@@ -162,27 +162,8 @@ class AssetEntry {
   getDynamicEntry() {
     const { fs } = this;
     const dir = this.pluginOption.get().entry;
-    const entryFilter = this.pluginOption.get().entryFilter;
-    const isFunctionEntryFilter = typeof entryFilter === 'function';
-    let includes = [this.pluginOption.get().test];
-    let excludes = [];
-
-    if (entryFilter && !isFunctionEntryFilter) {
-      if (entryFilter instanceof RegExp) {
-        includes = [entryFilter];
-      } else {
-        if (Array.isArray(entryFilter)) {
-          includes = entryFilter;
-        } else {
-          if ('includes' in entryFilter && Array.isArray(entryFilter.includes)) {
-            includes = entryFilter.includes;
-          }
-          if ('excludes' in entryFilter && Array.isArray(entryFilter.excludes)) {
-            excludes = entryFilter.excludes;
-          }
-        }
-      }
-    }
+    const { includes: filterIncludes, excludes, fn: filterFn } = this.pluginOption.getEntryFilter();
+    const includes = filterIncludes.length ? filterIncludes : [this.pluginOption.get().test];
 
     try {
       if (!fs.lstatSync(dir).isDirectory()) optionEntryPathException(dir);
@@ -194,7 +175,7 @@ class AssetEntry {
     const entry = {};
 
     files.forEach((file) => {
-      if (isFunctionEntryFilter && entryFilter(file) === false) {
+      if (filterFn(file) === false) {
         return;
       }
 

src/Plugin/Option.js

@@ -66,6 +66,7 @@ class Option {
     this.loaderPath = loaderPath;
     this.options = options;
     this.testEntry = null;
+    this.entryFilter = options.entryFilter;
     this.options.css = { ...this.css, ...this.options.css };
     this.options.js = { ...this.js, ...this.options.js };
 
@@ -279,6 +280,11 @@ class Option {
 
     // loader tests from rules have the highest priority, over defined in plugin options
     this.testEntry = loaderTests.size > 0 ? [...loaderTests] : [this.options.test];
+    this.normalizedEntryFilter = this.normalizeAdvancedFiler(this.testEntry, this.entryFilter);
+  }
+
+  getEntryFilter() {
+    return this.normalizedEntryFilter;
   }
 
   initWatchMode() {
@@ -749,6 +755,62 @@ class Option {
     return renderStage;
   }
 
+  /**
+   * Normalize the filter option defined by user and create inner structure of one.
+   *
+   * @param {RegExp} test
+   * @param {AdvancedFilter} filter
+   * @return {{includes: RegExp[], excludes: RegExp[], fn: function}}
+   */
+  normalizeAdvancedFiler(test, filter) {
+    const isFunction = typeof filter === 'function';
+    let fn = isFunction ? filter : () => true;
+    let includes = [];
+    let excludes = [];
+
+    if (filter && !isFunction) {
+      if (filter instanceof RegExp) {
+        includes = [filter];
+      } else {
+        if (Array.isArray(filter)) {
+          includes = filter;
+        } else {
+          if ('includes' in filter && Array.isArray(filter.includes)) {
+            includes = filter.includes;
+          }
+          if ('excludes' in filter && Array.isArray(filter.excludes)) {
+            excludes = filter.excludes;
+          }
+        }
+      }
+    }
+
+    return {
+      includes,
+      excludes,
+      fn,
+    };
+  }
+
+  /**
+   * Apply the advanced filter to a value.
+   *
+   * @param {string} value
+   * @param {NormalizedAdvancedFilter} filter
+   * @return {boolean}
+   */
+  applyAdvancedFiler(value, filter) {
+    const { includes, excludes, fn } = filter;
+
+    const hasIncludes = includes.length > 0;
+    const hasExcludes = excludes.length > 0;
+
+    const isIncluded = !hasIncludes || includes.some((regex) => regex.test(value));
+    const isExcluded = hasExcludes && excludes.some((regex) => regex.test(value));
+
+    return isIncluded && !isExcluded && fn(value) !== false;
+  }
+
   /**
    * Add default loader if it yet not defined.
    *

src/Plugin/Preload.js

@@ -131,8 +131,11 @@ class Preload {
       // if the property exists and have the undefined value, exclude this attribute in generating preload tag
       const hasType = 'type' in conf || (conf.attributes && 'type' in conf.attributes) || optionalTypeBy.has(attrs.as);
 
-      // save normalized attributes
-      conf._opts = { attrs, hasType };
+      // filter
+      const filter = this.pluginOption.normalizeAdvancedFiler(conf.test, conf.filter);
+
+      // save normalized options
+      conf._opts = { attrs, hasType, filter };
 
       groupBy[as] = [];
     }
@@ -148,17 +151,26 @@ class Preload {
         if (Array.isArray(item.chunks)) {
           // js
           for (let { chunkFile, assetFile } of item.chunks) {
-            preloadAssets.set(assetFile, conf._opts);
+            if (this.pluginOption.applyAdvancedFiler(assetFile, conf._opts.filter)) {
+              preloadAssets.set(assetFile, conf._opts);
+            }
           }
         } else {
-          // css
-          preloadAssets.set(item.assetFile, conf._opts);
+          //console.log('-- assetFile: ', item);
+          // css, images, fonts, etc
+          if (this.pluginOption.applyAdvancedFiler(item.assetFile, conf._opts.filter)) {
+            preloadAssets.set(item.assetFile, conf._opts);
+          }
+
+          //preloadAssets.set(item.assetFile, conf._opts);
         }
 
-        // dynamic imported modules
+        // dynamic imported modules, asyncChunks
         if (Array.isArray(item.children)) {
           for (let { chunkFile, assetFile } of item.children) {
-            preloadAssets.set(assetFile, conf._opts);
+            if (this.pluginOption.applyAdvancedFiler(assetFile, conf._opts.filter)) {
+              preloadAssets.set(assetFile, conf._opts);
+            }
           }
         }
       }
@@ -175,7 +187,9 @@ class Preload {
             ? this.getPreloadFile(data.entry, assetItem.issuer, assetItem.assetFile)
             : assetItem.assetFile;
 
-          preloadAssets.set(preloadFile, conf._opts);
+          if (this.pluginOption.applyAdvancedFiler(preloadFile, conf._opts.filter)) {
+            preloadAssets.set(preloadFile, conf._opts);
+          }
         }
       }
     }

test/cases/option-preload-dynamic-import-filter/expected/css/style.0d25913e.css

@@ -0,0 +1,9 @@
+@font-face {
+  font-family: 'OpenSans';
+  src: url(../fonts/open-sans-regular.woff2) format('woff2');
+  font-style: normal;
+}
+
+h1 {
+  color: orangered;
+}

test/cases/option-preload-dynamic-import-filter/expected/fonts/open-sans-regular.woff2

@@ -0,0 +1,16 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Test</title>
+    <link rel="preload" href="../js/main.e334d98a.js" as="script">
+    <link rel="preload" href="../js/module1.chunk.js" as="script">
+    <link rel="preload" href="../css/style.0d25913e.css" as="style">
+    <link rel="preload" href="../fonts/open-sans-regular.woff2" as="font" type="font/woff2" crossorigin>
+    <link href="../css/style.0d25913e.css" rel="stylesheet">
+    <script src="../js/main.e334d98a.js" defer="defer"></script>
+  </head>
+  <body>
+    <h1>Hello World!</h1>
+    <script src="../js/no-preload.e730d102.js" defer="defer"></script>
+  </body>
+</html>