feat: add support for the template function on the client-side for ejs

Author: webdiscus

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Change log
 
+## 3.4.0 (2023-12-03)
+
+- feat: add support for the template function on the client-side for `ejs`
+- docs: update readme
+- test: add tests for compile mode
+
 ## 3.3.0 (2023-11-29)
 
 - feat: add support for the template function on the client-side for `eta`

README.md

@@ -4096,14 +4096,21 @@ The [preprocessor](#loader-option-preprocessor) works in two modes: `render` and
 
 ### Render mode
 
-The `render` is default mode for a template defined in the [entry](#option-entry) option.
-The processed template in `render` mode is HTML string, which is saved as HTML file.
-You can import a template file as generated HTML string in JS with the `?render` query.
+The `render` is the default mode for the template defined in the [entry](#option-entry) option.
+The rendered template is an HTML string, which is saved as an HTML file.
+
+You can import the template file as a generated HTML string in JS using the `?render` query.
+To pass simple variables into the imported template you can use query parameters, e.g.: `?render&name=Arnold&age=25`.
+To pass complex variables such as an array or an object use the global [data](#option-data) option.
+
+> **Note**
+> 
+> At runtime in JavaScript will be used the already rendered HTML from the template.
 
 For example:
 
 ```js
-import html from './partials/star-button.html?render';
+import html from './partials/star-button.html?render&buttonText=Star';
 
 document.getElementById('star-button').innerHTML = html;
 ```
@@ -4114,15 +4121,16 @@ _./partials/star-button.html_
   <!-- you can use a source image file with webpack alias,
        in the bundle it will be auto replaced with the output asset filename -->
   <img src="@images/star.svg">
-  <span>Star</span>
+  <!-- the `buttonText` variable is passed via query -->
+  <span><%= buttonText %></span>
 </button>
 ```
 
 ### Compile mode
 
-The `compile` is default mode for a template imported in JavaScript file.
-The processed template in `compile` mode is a template function,
-which can be executed with passed variables in the runtime on client-side.
+The `compile` is the default mode for the template imported in JavaScript file.
+The compiled template is a template function,
+which can be executed with passed variables in the runtime on the client-side in the browser.
 
 For example:
 
@@ -4159,10 +4167,10 @@ _./partials/people.ejs_
 
 #### Template engines that do support the `template function` on client-side
 
-- [eta](#loader-option-preprocessor-options-eta) - generates a fast small template function with runtime (~3KB) (**recommended**)\
+- [eta](#loader-option-preprocessor-options-eta) - generates a template function with runtime (~3KB)\
+  `include` is supported
+- [ejs](#loader-option-preprocessor-options-ejs) - generates a fast smallest pure template function w/o runtime (**recommended** for use on client-side)\
   `include` is supported
-- [ejs](#loader-option-preprocessor-options-ejs) - generates a fast small pure template function w/o runtime\
-  `include` is NOT supported (yet)
 - [handlebars](#loader-option-preprocessor-options-handlebars) - generates a precompiled template with runtime (~28KB)\
   `include` is NOT supported (yet)
 - [nunjucks](#loader-option-preprocessor-options-nunjucks) - generates a precompiled template with runtime (~41KB)\

images/plugin-logo.pxd

@@ -1,6 +1,6 @@
 {
   "name": "html-bundler-webpack-plugin",
-  "version": "3.3.0",
+  "version": "3.4.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",

package.json

@@ -13,9 +13,7 @@ class Loader {
    */
   static init(loaderContext) {
     const { rootContext, hot } = loaderContext;
-    const { preprocessor, preprocessorMode, data, esModule, self: useSelf } = Option.get();
-
-    //this.data = data;
+    const { preprocessor, preprocessorMode, esModule, self: useSelf } = Option.get();
 
     // prevent double initialization with same options, it occurs when many entry files used in one webpack config
     if (!PluginService.isCached(rootContext)) {
@@ -56,12 +54,12 @@ class Loader {
   /**
    * Export generated result.
    *
-   * @param {string} source
+   * @param {string} content
    * @param {BundlerPluginLoaderContext} loaderContext
    * @return {string}
    */
-  static export(source, loaderContext) {
-    return this.compiler.export(source, loaderContext);
+  static export(content, loaderContext) {
+    return this.compiler.export(content, loaderContext);
   }
 
   /**

src/Loader/Loader.js

@@ -43,11 +43,12 @@ class Render extends PreprocessorMode {
    * Export template code with rendered HTML.
    *
    * @param {string} content The template content.
-   * @param {{}} data The object with variables passed in template.
-   * @param {string} issuer The issuer of the template file.
+   * @param {BundlerPluginLoaderContext} loaderContext
    * @return {string}
    */
-  export(content, { data, resource: issuer }) {
+  export(content, loaderContext) {
+    const { resource: issuer } = loaderContext;
+
     /* istanbul ignore next: Webpack API no provide `loaderContext.hot` for testing */
     if (this.hot && PluginService.useHotUpdate()) {
       content = this.injectHotScript(content);

src/Loader/Modes/Render.js

@@ -119,7 +119,7 @@ class Option {
 
       // watch only files matched to RegExps,
       // if empty then watch all files, except ignored
-      files: [PluginService.getOptions().getFilterRegexp()],
+      files: PluginService.getOptions().getEntryTest(),
 
       // ignore paths and files matched to RegExps
       ignore: [

src/Loader/Option.js

@@ -3,6 +3,8 @@ const { unsupportedPreprocessorException } = require('./Messages/Exeptions');
 /** @typedef {import('webpack').LoaderContext} LoaderContext */
 
 class Preprocessor {
+  static cache = new Map();
+
   /**
    * Whether the preprocessor is used.
    *
@@ -16,11 +18,60 @@ class Preprocessor {
   }
 
   /**
-   * Returns preprocessor to render/compile a template.
-   * The default preprocessor uses the Eta templating engine.
+   * Load preprocessor module.
+   * The default preprocessor uses the Eta template engine.
+   *
+   * @param {string|function|boolean|undefined} preprocessor
+   * @return {*} TODO: add jsdoc for the preprocessor module type
+   * @throws
+   */
+  static load(preprocessor) {
+    const preprocessorDirs = {
+      eta: 'Eta',
+      ejs: 'Ejs',
+      handlebars: 'Handlebars',
+      nunjucks: 'Nunjucks',
+      twig: 'Twig',
+    };
+
+    // disabled preprocessor
+    if (preprocessor === false) return null;
+
+    // default preprocessor is Eta
+    if (preprocessor == null) preprocessor = 'eta';
+
+    if (this.cache.has(preprocessor)) {
+      return this.cache.get(preprocessor);
+    }
+
+    let dirname = preprocessorDirs[preprocessor];
+
+    if (dirname) {
+      // we are sure the file exists
+      const module = require(`./Preprocessors/${dirname}/index.js`);
+      this.cache.set(preprocessor, module);
+
+      return module;
+    }
+
+    unsupportedPreprocessorException(preprocessor);
+  }
+
+  /**
+   * @param {*} preprocessor
+   * @return {RegExp|null}
+   */
+  static getTest(preprocessor) {
+    const module = typeof preprocessor === 'function' ? preprocessor : this.load(preprocessor);
+
+    return module?.test;
+  }
+
+  /**
+   * Returns a preprocessor method to render/compile a template.
    *
    * @param {Object} options The loader options.
-   * @return {null|(function(string, {data?: {}}): Promise|null)}
+   * @return {null|(function(string, loaderContext: BundlerPluginLoaderContext): Promise|null)}
    */
   static getPreprocessor(options) {
     const { preprocessor, preprocessorMode } = options;
@@ -36,37 +87,17 @@ class Preprocessor {
 
   /**
    * Factory preprocessor as a function.
-   * The default preprocessor uses the Eta template engine.
    *
-   * @param {LoaderContext} loaderContext The loader context of Webpack.
+   * @param {BundlerPluginLoaderContext} loaderContext The loader context of Webpack.
    * @param {string|null|*} preprocessor The preprocessor value, should be a string
    * @param {Object} options The preprocessor options.
-   * @param {Function} watch The function called by watching.
+   * @param {boolean} watch Whether is serve/watch mode.
    * @return {Function|Promise|Object}
-   * @throws
    */
   static factory(loaderContext, { preprocessor, options = {}, watch }) {
-    if (preprocessor == null) preprocessor = 'eta';
-
-    switch (preprocessor) {
-      case 'eta':
-        return require('./Preprocessors/Eta/index.js')(loaderContext, options);
-
-      case 'ejs':
-        return require('./Preprocessors/Ejs/index.js')(loaderContext, options);
+    const module = this.load(preprocessor);
 
-      case 'handlebars':
-        return require('./Preprocessors/Handlebars/index.js')(loaderContext, options);
-
-      case 'nunjucks':
-        return require('./Preprocessors/Nunjucks/index.js')(loaderContext, options, watch);
-
-      case 'twig':
-        return require('./Preprocessors/Twig/index.js')(loaderContext, options);
-
-      default:
-        unsupportedPreprocessorException(preprocessor);
-    }
+    return module(loaderContext, options, watch);
   }
 
   static watchRun({ preprocessor }) {

src/Loader/Preprocessor.js

@@ -1,12 +1,17 @@
 const { loadModule } = require('../../../Common/FileUtils');
 const { stringifyData } = require('../../Utils');
 
+// replace the partial file and data to load nested included template via the Webpack loader
+// include("./file.html")                   => require("./file.eta")({...locals, ...{}})
+// include('./file.html', { name: 'Siri' }) => require('./file.eta')({...locals, ...{name: 'Siri'}})
+const includeRegexp = /include\((.+?)(?:\)|,\s*{(.+?)}\))/g;
+
 /**
- * Transform the raw template to template function or HTML.
+ * Transform the raw template source to a template function or HTML.
  *
- * @param {{}} loaderContext
+ * @param {BundlerPluginLoaderContext} loaderContext
  * @param {{}} options
- * @return {function(template: string, {resourcePath: string, data?: {}}, {preprocessorMode: string}): string}
+ * @return {{compile: (function(string, {resourcePath: string, data?: {}}): *), render: (function(string, {resourcePath: string, data?: {}}): *), export: (function(string, {data: {}}): string)}}
  */
 const preprocessor = (loaderContext, options) => {
   const Ejs = loadModule('ejs');
@@ -22,38 +27,36 @@ const preprocessor = (loaderContext, options) => {
      * @param {{}} data
      * @return {string}
      */
-    render: (source, { resourcePath, data = {} }) =>
-      Ejs.render(source, data, {
+    render(source, { resourcePath, data = {} }) {
+      return Ejs.render(source, data, {
         async: false,
         root: rootContext, // root path for includes with an absolute path (e.g., /file.html)
         ...options,
         filename: resourcePath, // allow including a partial relative to the template
-      }),
+      });
+    },
 
     /**
      * Compile template into template function.
      * Called when a template is loaded in JS in `compile` mode.
      *
-     * TODO: add support for the `include`
-     *
      * @param {string} source The template source code.
      * @param {string} resourcePath
      * @param {{}} data
      * @return {string}
      */
-    compile: (source, { resourcePath, data = {} }) => {
-      let templateFunction = Ejs.compile(source, {
-        client: true,
+    compile(source, { resourcePath, data = {} }) {
+      return Ejs.compile(source, {
         compileDebug: false,
-        root: rootContext, // root path for includes with an absolute path (e.g., /file.html)
+        root: rootContext,
         ...options,
-        async: false, // for client is used the sync function
+        client: true,
+        async: false,
         filename: resourcePath, // allow including a partial relative to the template
-      }).toString();
-
-      return templateFunction
-        .replace(`var __output = "";`, 'locals = Object.assign(__data__, locals); var __output = "";')
-        .replaceAll('include(', 'require(');
+        context: data,
+      })
+        .toString()
+        .replaceAll(includeRegexp, `require($1)({...locals, ...{$2}})`);
     },
 
     /**
@@ -64,14 +67,18 @@ const preprocessor = (loaderContext, options) => {
      * @param {{}} data The object with variables passed in template.
      * @return {string} The exported template function.
      */
-    export: (templateFunction, { data }) => {
+    export(templateFunction, { data }) {
       // the name of template function in generated code
       const exportFunction = 'anonymous';
       const exportCode = 'module.exports=';
 
-      return `var __data__ = ${stringifyData(data)};` + templateFunction + `;${exportCode}${exportFunction};`;
+      return `${templateFunction};
+        var __data__ = ${stringifyData(data)};
+        var template = (context) => ${exportFunction}(Object.assign(__data__, context));
+        ${exportCode}template;`;
     },
   };
 };
 
 module.exports = preprocessor;
+module.exports.test = /\.(html|ejs)$/;