feat: add entryFilter option

Author: webdiscus

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Change log
 
+## 3.11.0 (2024-04-23)
+
+- feat: add `entryFilter` option to include or exclude entry files when the `entry` option is the path
+
 ## 3.10.0 (2024-04-18)
 
 - feat: add support the [CSS Modules](https://github.com/css-modules/css-modules) for styles imported in JS using the [css-loader modules](https://github.com/webpack-contrib/css-loader#modules) option.\

README.md

@@ -472,6 +472,7 @@ See [boilerplate](https://github.com/webdiscus/webpack-html-scss-boilerplate)
      - [entry as a path](#option-entry-path) (find templates in a directory recursively)
      - [entry data](#option-entry-data) (pass data in the single template as an object or a file)
    - [entry dynamic](#option-entry-path) (entry as a path to template files)
+   - [entryFilter](#option-entry-filter) (filter for entry dynamic)
    - [outputPath](#option-outputpath) (output path of HTML file)
    - [filename](#option-filename) (output filename of HTML file)
    - [js](#option-js) (options for JS)
@@ -542,7 +543,6 @@ See [boilerplate](https://github.com/webdiscus/webpack-html-scss-boilerplate)
 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)
-   - Design system NIHR: Components, Elements, Layouts (`Handlebars`) [demo](https://design-system.nihr.ac.uk) | [source](https://github.com/webdiscus/design-system)
    - Asia restaurant (`Nunjucks`) [demo](https://webdiscus.github.io/demo-asia-restaurant-bundler-plugin) | [source](https://github.com/webdiscus/demo-asia-restaurant-bundler-plugin)
    - 10up / Animation Best Practices [demo](https://animation.10up.com/) | [source](https://github.com/10up/animation-best-practices)
 1. <a id="usage-examples" name="usage-examples"></a>
@@ -1561,6 +1561,95 @@ new HtmlBundlerPlugin({
 
 #### [↑ back to contents](#contents)
 
+<a id="option-entry-filter" name="option-entry-filter"></a>
+
+### `entryFilter`
+
+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 = 
+  | RegExp
+  | Array<RegExp>
+  | { includes?: Array<RegExp>; excludes?: Array<RegExp> }
+  | ((file: string) => void | false);
+```
+
+Default value:
+
+```ts
+{
+  includes: [
+    /\.(html|eta)$/,
+  ], 
+  excludes: [] 
+}
+```
+
+The default `includes` property depends on the used [preprocessor](#loader-option-preprocessor) option.
+Each preprocessor has its own filter to include from the entry path only relevant template files.
+
+#### `entryFilter` as `RegExp`
+
+The filter works as `include` only files that match the regular expressions.
+For example:
+```js
+new HtmlBundlerPlugin({
+  entry: 'src/views/pages/',
+  entryFilter: /index\.html$/, // render only `index.html` files in all sub dirs
+})
+```
+
+#### `entryFilter` as `Array<RegExp>`
+
+The filter works as `include` only files that match one of the regular expressions.
+For example:
+```js
+new HtmlBundlerPlugin({
+  entry: 'src/views/pages/',
+  entryFilter: [
+    // render only page specifically files, e.g.: `index.html`, `contact.html`, `about.html`
+    /index\.html$/,
+    /contact\.html$/,
+    /about\.html$/,
+  ],
+})
+```
+
+#### `entryFilter` as `{ includes: Array<RegExp>, excludes: Array<RegExp> }`
+
+The filter includes only files that match one of the regular expressions, except excluded files.
+For example:
+```js
+new HtmlBundlerPlugin({
+  entry: 'src/views/pages/',
+  entryFilter: {
+    includes: [/\.(html|eta)$/,], // render all `.html` and `.eta` template files
+    excludes: [/partial/],  // except partial files
+  },
+})
+``` 
+
+#### `entryFilter` as `callback`
+
+In addition to the default `includes` filter, this filter works as `exclude` a file if it returns `false`.
+If the callback returns `true` or nothing, then the file will be processed.
+
+For example:
+```js
+new HtmlBundlerPlugin({
+  entry: 'src/views/pages/',
+  entryFilter: (file) => {
+    if (/partial/.test(file)) return false; // ignore files containing the `partial` in the path
+  },
+})
+```
+The `file` argument is the absolute path of a template file.
+
+#### [↑ back to contents](#contents)
+
 <a id="option-outputpath" name="option-outputpath"></a>
 
 ### `outputPath`
@@ -2705,7 +2794,7 @@ The `HtmlBundlerPlugin.loader` will be added automatically.
 
 For example, both configurations are functionally identical:
 
-_1) the variant using the `loaderOptions`_ (recommended for common use cases)
+_1) the variant using the `loaderOptions`_, **recommended** for common use cases:
 
 ```js
 const HtmlBundlerPlugin = require('html-bundler-webpack-plugin');
@@ -2715,18 +2804,18 @@ module.exports = {
       entry: {
         index: 'src/views/index.ejs',
       },
+      // compile a template into HTML using `ejs` module
+      preprocessor: 'ejs',
       loaderOptions: {
         // resolve files specified in non-standard attributes 'data-src', 'data-srcset'
         sources: [{ tag: 'img', attributes: ['data-src', 'data-srcset'] }],
-        // compile a template into HTML using `ejs` module
-        preprocessor: 'ejs',
       },
     }),
   ],
 };
 ```
 
-_2) the variant using the `module.rules`_
+_2) the `low level` variant using the `module.rules`_:
 
 ```js
 const HtmlBundlerPlugin = require('html-bundler-webpack-plugin');
@@ -2753,10 +2842,13 @@ module.exports = {
 };
 ```
 
-For common use cases, the first option is recommended. So your config is smaller and cleaner.
-
-The second variant use only for special cases, e.g. when you have templates with different syntax.
-An example see by [How to use some different template engines](#recipe-diff-templates).
+> ⚠️ **Warning**
+> 
+> If you don't know what it's for, don't define a module rule for template files.
+> The plugin automatically configures this rule.
+> 
+> Define this rule only for special cases, e.g. when you have templates with different templating engines.\
+> An example see by [How to use some different template engines](#recipe-diff-templates).
 
 > **Note**
 >
@@ -3151,7 +3243,7 @@ module.exports = {
 > **Note**
 >
 > Since the `v2.2.0` is available new syntax, the [preprocessor](#option-preprocessor)
-> and the [preprocessorOptions](#option-preprocessor) can be defined directly in the plugin option
+> and the [preprocessorOptions](#option-preprocessor) should be defined directly in the plugin option
 > to simplify the config:
 >
 > ```js

package.json

@@ -1,6 +1,6 @@
 {
   "name": "html-bundler-webpack-plugin",
-  "version": "3.10.0",
+  "version": "3.11.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/AssetCompiler.js

@@ -268,11 +268,8 @@ class AssetCompiler {
       PluginService.watchRun();
     });
 
-    // TODO:
-    //  - before AssetEntry.initEntry() init preprocessor by Loader.Options to get `test`
-
     // entry option
-    AssetEntry.initEntry();
+    AssetEntry.init({ fs: this.fs, entryLibrary: this.entryLibrary, collection: Collection });
     compiler.hooks.entryOption.tap(pluginName, this.afterProcessEntry);
 
     // watch changes for entry-points
@@ -289,7 +286,7 @@ class AssetCompiler {
       PluginService.plugin = AssetCompiler;
       PluginService.compilation = compilation;
 
-      AssetEntry.init({ compilation, entryLibrary: this.entryLibrary, collection: Collection });
+      AssetEntry.initCompilation(compilation);
       AssetTrash.init(compilation);
       CssExtractModule.init(compilation);
       Collection.init({ compilation, assetEntry: AssetEntry, hooks: AssetCompiler.getHooks(compilation) });

src/Plugin/AssetEntry.js

@@ -1,4 +1,3 @@
-const fs = require('fs');
 const path = require('path');
 const Option = require('./Option');
 const PluginService = require('./PluginService');
@@ -82,21 +81,18 @@ class AssetEntry {
   static entryNamePrefix = '__bundler-plugin-entry__';
 
   /**
-   * Init the object, inject dependencies.
+   * Init the asset entry.
    *
-   * @param {Compilation} compilation
+   * @param {FileSystem} fs
    * @param {Object} entryLibrary
    * @param {Collection} collection
    */
-  static init({ compilation, entryLibrary, collection }) {
-    this.compilation = compilation;
+  static init({ fs, entryLibrary, collection }) {
+    this.fs = fs;
     this.entryLibrary = entryLibrary;
     this.collection = collection;
-    this.fs = compilation.compiler.inputFileSystem.fileSystem;
     this.entryIdRegexp = new RegExp(`\\?${this.entryIdKey}=(\\d+)`);
-  }
 
-  static initEntry() {
     const { entry } = Option.webpackOptions;
     let pluginEntry;
 
@@ -136,26 +132,60 @@ class AssetEntry {
     Option.webpackOptions.entry = pluginEntry;
   }
 
+  /**
+   * Init for the compilation.
+   *
+   * @param {Compilation} compilation
+   */
+  static initCompilation(compilation) {
+    this.compilation = compilation;
+  }
+
   /**
    * Returns dynamic entries read recursively from the entry path.
    *
    * @return {Object}
    * @throws
    */
   static getDynamicEntry() {
-    //const { fs } = this; // TODO: fix error with injected fs
+    const { fs } = this;
     const dir = Option.get().entry;
+    const entryFilter = Option.get().entryFilter;
+    const isFunctionEntryFilter = typeof entryFilter === 'function';
+    let includes = [Option.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;
+          }
+        }
+      }
+    }
 
     try {
       if (!fs.lstatSync(dir).isDirectory()) optionEntryPathException(dir);
     } catch (error) {
       optionEntryPathException(dir);
     }
 
-    const files = readDirRecursiveSync(dir, { fs, includes: [Option.get().test] });
+    const files = readDirRecursiveSync(dir, { fs, includes, excludes });
     const entry = {};
 
     files.forEach((file) => {
+      if (isFunctionEntryFilter && entryFilter(file) === false) {
+        return;
+      }
+
       const outputFile = path.relative(dir, file);
       const name = outputFile.slice(0, outputFile.lastIndexOf('.'));
       const entryName = this.createEntryName(name);