html-webpack-plugin 4.0.2 → 4.2.0

package/lib/cached-child-compiler.js

@@ -0,0 +1,379 @@
+// @ts-check
+/**
+ * @file
+ * Helper plugin manages the cached state of the child compilation
+ *
+ * To optimize performance the child compilation is running asyncronously.
+ * Therefore it needs to be started in the compiler.make phase and ends after
+ * the compilation.afterCompile phase.
+ *
+ * To prevent bugs from blocked hooks there is no promise or event based api
+ * for this plugin.
+ *
+ * Example usage:
+ *
+ * ```js
+    const childCompilerPlugin = new PersistentChildCompilerPlugin();
+    childCompilerPlugin.addEntry('./src/index.js');
+    compiler.hooks.afterCompile.tapAsync('MyPlugin', (compilation, callback) => {
+      console.log(childCompilerPlugin.getCompilationResult()['./src/index.js']));
+      return true;
+    });
+ * ```
+ */
+
+// Import types
+/** @typedef {import("webpack/lib/Compiler.js")} WebpackCompiler */
+/** @typedef {import("webpack/lib/Compilation.js")} WebpackCompilation */
+/** @typedef {{hash: string, entry: any, content: string }} ChildCompilationResultEntry */
+/** @typedef {import("./webpack4/file-watcher-api").Snapshot} Snapshot */
+/** @typedef {{fileDependencies: string[], contextDependencies: string[], missingDependencies: string[]}} FileDependencies */
+/** @typedef {{
+  dependencies: FileDependencies,
+  compiledEntries: {[entryName: string]: ChildCompilationResultEntry}
+} | {
+  dependencies: FileDependencies,
+  error: Error
+}} ChildCompilationResult */
+'use strict';
+
+const { HtmlWebpackChildCompiler } = require('./child-compiler');
+const fileWatcherApi = require('./file-watcher-api');
+
+/**
+ * This plugin is a singleton for performance reasons.
+ * To keep track if a plugin does already exist for the compiler they are cached
+ * in this map
+ * @type {WeakMap<WebpackCompiler, PersistentChildCompilerSingletonPlugin>}}
+ */
+const compilerMap = new WeakMap();
+
+class CachedChildCompilation {
+  /**
+   * @param {WebpackCompiler} compiler
+   */
+  constructor (compiler) {
+    /**
+     * @private
+     * @type {WebpackCompiler}
+     */
+    this.compiler = compiler;
+    // Create a singlton instance for the compiler
+    // if there is none
+    if (compilerMap.has(compiler)) {
+      return;
+    }
+    const persistentChildCompilerSingletonPlugin = new PersistentChildCompilerSingletonPlugin();
+    compilerMap.set(compiler, persistentChildCompilerSingletonPlugin);
+    persistentChildCompilerSingletonPlugin.apply(compiler);
+  }
+
+  /**
+   * apply is called by the webpack main compiler during the start phase
+   * @param {string} entry
+   */
+  addEntry (entry) {
+    const persistentChildCompilerSingletonPlugin = compilerMap.get(this.compiler);
+    if (!persistentChildCompilerSingletonPlugin) {
+      throw new Error(
+        'PersistentChildCompilerSingletonPlugin instance not found.'
+      );
+    }
+    persistentChildCompilerSingletonPlugin.addEntry(entry);
+  }
+
+  getCompilationResult () {
+    const persistentChildCompilerSingletonPlugin = compilerMap.get(this.compiler);
+    if (!persistentChildCompilerSingletonPlugin) {
+      throw new Error(
+        'PersistentChildCompilerSingletonPlugin instance not found.'
+      );
+    }
+    return persistentChildCompilerSingletonPlugin.getLatestResult();
+  }
+
+  /**
+   * Returns the result for the given entry
+   * @param {string} entry
+   * @returns {
+      | { mainCompilationHash: string, error: Error }
+      | { mainCompilationHash: string, compiledEntry: ChildCompilationResultEntry }
+    }
+   */
+  getCompilationEntryResult (entry) {
+    const latestResult = this.getCompilationResult();
+    const compilationResult = latestResult.compilationResult;
+    return 'error' in compilationResult ? {
+      mainCompilationHash: latestResult.mainCompilationHash,
+      error: compilationResult.error
+    } : {
+      mainCompilationHash: latestResult.mainCompilationHash,
+      compiledEntry: compilationResult.compiledEntries[entry]
+    };
+  }
+}
+
+class PersistentChildCompilerSingletonPlugin {
+  constructor () {
+    /**
+     * @private
+     * @type {
+      | {
+        isCompiling: false,
+        isVerifyingCache: false,
+        entries: string[],
+        compiledEntries: string[],
+        mainCompilationHash: string,
+        compilationResult: ChildCompilationResult
+      }
+    | Readonly<{
+      isCompiling: false,
+      isVerifyingCache: true,
+      entries: string[],
+      previousEntries: string[],
+      previousResult: ChildCompilationResult
+    }>
+    | Readonly <{
+      isVerifyingCache: false,
+      isCompiling: true,
+      entries: string[],
+    }>
+  } the internal compilation state */
+    this.compilationState = {
+      isCompiling: false,
+      isVerifyingCache: false,
+      entries: [],
+      compiledEntries: [],
+      mainCompilationHash: 'initial',
+      compilationResult: {
+        dependencies: {
+          fileDependencies: [],
+          contextDependencies: [],
+          missingDependencies: []
+        },
+        compiledEntries: {}
+      }
+    };
+  }
+
+  /**
+   * apply is called by the webpack main compiler during the start phase
+   * @param {WebpackCompiler} compiler
+   */
+  apply (compiler) {
+    /** @type Promise<ChildCompilationResult> */
+    let childCompilationResultPromise = Promise.resolve({
+      dependencies: {
+        fileDependencies: [],
+        contextDependencies: [],
+        missingDependencies: []
+      },
+      compiledEntries: {}
+    });
+    /**
+     * The main compilation hash which will only be updated
+     * if the childCompiler changes
+     */
+    let mainCompilationHashOfLastChildRecompile = '';
+    /** @typedef{Snapshot|undefined} */
+    let previousFileSystemSnapshot;
+    let compilationStartTime = new Date().getTime();
+
+    compiler.hooks.make.tapAsync(
+      'PersistentChildCompilerSingletonPlugin',
+      (mainCompilation, callback) => {
+        if (this.compilationState.isCompiling || this.compilationState.isVerifyingCache) {
+          return callback(new Error('Child compilation has already started'));
+        }
+
+        // Update the time to the current compile start time
+        compilationStartTime = new Date().getTime();
+
+        // The compilation starts - adding new templates is now not possible anymore
+        this.compilationState = {
+          isCompiling: false,
+          isVerifyingCache: true,
+          previousEntries: this.compilationState.compiledEntries,
+          previousResult: this.compilationState.compilationResult,
+          entries: this.compilationState.entries
+        };
+
+        // Validate cache:
+        const isCacheValidPromise = this.isCacheValid(previousFileSystemSnapshot, mainCompilation);
+
+        let cachedResult = childCompilationResultPromise;
+        childCompilationResultPromise = isCacheValidPromise.then((isCacheValid) => {
+          // Reuse cache
+          if (isCacheValid) {
+            return cachedResult;
+          }
+          // Start the compilation
+          const compiledEntriesPromise = this.compileEntries(
+            mainCompilation,
+            this.compilationState.entries
+          );
+          // Update snapshot as soon as we know the filedependencies
+          // this might possibly cause bugs if files were changed inbetween
+          // compilation start and snapshot creation
+          compiledEntriesPromise.then((childCompilationResult) => {
+            return fileWatcherApi.createSnapshot(childCompilationResult.dependencies, mainCompilation, compilationStartTime);
+          }).then((snapshot) => {
+            previousFileSystemSnapshot = snapshot;
+          });
+          return compiledEntriesPromise;
+        });
+
+        // Add files to compilation which needs to be watched:
+        mainCompilation.hooks.optimizeTree.tapAsync(
+          'PersistentChildCompilerSingletonPlugin',
+          (chunks, modules, callback) => {
+            const handleCompilationDonePromise = childCompilationResultPromise.then(
+              childCompilationResult => {
+                this.watchFiles(
+                  mainCompilation,
+                  childCompilationResult.dependencies
+                );
+              });
+            handleCompilationDonePromise.then(() => callback(null, chunks, modules), callback);
+          }
+        );
+
+        // Store the final compilation once the main compilation hash is known
+        mainCompilation.hooks.additionalAssets.tapAsync(
+          'PersistentChildCompilerSingletonPlugin',
+          (callback) => {
+            const didRecompilePromise = Promise.all([childCompilationResultPromise, cachedResult]).then(
+              ([childCompilationResult, cachedResult]) => {
+                // Update if childCompilation changed
+                return (cachedResult !== childCompilationResult);
+              }
+            );
+
+            const handleCompilationDonePromise = Promise.all([childCompilationResultPromise, didRecompilePromise]).then(
+              ([childCompilationResult, didRecompile]) => {
+                // Update hash and snapshot if childCompilation changed
+                if (didRecompile) {
+                  mainCompilationHashOfLastChildRecompile = mainCompilation.hash;
+                }
+                this.compilationState = {
+                  isCompiling: false,
+                  isVerifyingCache: false,
+                  entries: this.compilationState.entries,
+                  compiledEntries: this.compilationState.entries,
+                  compilationResult: childCompilationResult,
+                  mainCompilationHash: mainCompilationHashOfLastChildRecompile
+                };
+              });
+            handleCompilationDonePromise.then(() => callback(null), callback);
+          }
+        );
+
+        // Continue compilation:
+        callback(null);
+      }
+    );
+  }
+
+  /**
+   * Add a new entry to the next compile run
+   * @param {string} entry
+   */
+  addEntry (entry) {
+    if (this.compilationState.isCompiling || this.compilationState.isVerifyingCache) {
+      throw new Error(
+        'The child compiler has already started to compile. ' +
+        "Please add entries before the main compiler 'make' phase has started or " +
+        'after the compilation is done.'
+      );
+    }
+    if (this.compilationState.entries.indexOf(entry) === -1) {
+      this.compilationState.entries = [...this.compilationState.entries, entry];
+    }
+  }
+
+  getLatestResult () {
+    if (this.compilationState.isCompiling || this.compilationState.isVerifyingCache) {
+      throw new Error(
+        'The child compiler is not done compiling. ' +
+        "Please access the result after the compiler 'make' phase has started or " +
+        'after the compilation is done.'
+      );
+    }
+    return {
+      mainCompilationHash: this.compilationState.mainCompilationHash,
+      compilationResult: this.compilationState.compilationResult
+    };
+  }
+
+  /**
+   * Verify that the cache is still valid
+   * @private
+   * @param {Snapshot | undefined} snapshot
+   * @param {WebpackCompilation} mainCompilation
+   * @returns {Promise<boolean>}
+   */
+  isCacheValid (snapshot, mainCompilation) {
+    if (!this.compilationState.isVerifyingCache) {
+      return Promise.reject(new Error('Cache validation can only be done right before the compilation starts'));
+    }
+    // If there are no entries we don't need a new child compilation
+    if (this.compilationState.entries.length === 0) {
+      return Promise.resolve(true);
+    }
+    // If there are new entries the cache is invalid
+    if (this.compilationState.entries !== this.compilationState.previousEntries) {
+      return Promise.resolve(false);
+    }
+    // Mark the cache as invalid if there is no snapshot
+    if (!snapshot) {
+      return Promise.resolve(false);
+    }
+    return fileWatcherApi.isSnapShotValid(snapshot, mainCompilation);
+  }
+
+  /**
+   * Start to compile all templates
+   *
+   * @private
+   * @param {WebpackCompilation} mainCompilation
+   * @param {string[]} entries
+   * @returns {Promise<ChildCompilationResult>}
+   */
+  compileEntries (mainCompilation, entries) {
+    const compiler = new HtmlWebpackChildCompiler(entries);
+    return compiler.compileTemplates(mainCompilation).then((result) => {
+      return {
+      // The compiled sources to render the content
+        compiledEntries: result,
+        // The file dependencies to find out if a
+        // recompilation is required
+        dependencies: compiler.fileDependencies,
+        // The main compilation hash can be used to find out
+        // if this compilation was done during the current compilation
+        mainCompilationHash: mainCompilation.hash
+      };
+    }, error => ({
+      // The compiled sources to render the content
+      error,
+      // The file dependencies to find out if a
+      // recompilation is required
+      dependencies: compiler.fileDependencies,
+      // The main compilation hash can be used to find out
+      // if this compilation was done during the current compilation
+      mainCompilationHash: mainCompilation.hash
+    }));
+  }
+
+  /**
+   * @private
+   * @param {WebpackCompilation} mainCompilation
+   * @param {FileDependencies} files
+   */
+  watchFiles (mainCompilation, files) {
+    fileWatcherApi.watchFiles(mainCompilation, files);
+  }
+}
+
+module.exports = {
+  CachedChildCompilation
+};

package/lib/child-compiler.js

@@ -0,0 +1,183 @@
+// @ts-check
+/** @typedef {import("webpack/lib/Compilation.js")} WebpackCompilation */
+/** @typedef {import("webpack/lib/Compiler.js")} WebpackCompiler */
+/** @typedef {import("webpack/lib/Chunk.js")} WebpackChunk */
+'use strict';
+/**
+ * @file
+ * This file uses webpack to compile a template with a child compiler.
+ *
+ * [TEMPLATE] -> [JAVASCRIPT]
+ *
+ */
+'use strict';
+const NodeTemplatePlugin = require('webpack/lib/node/NodeTemplatePlugin');
+const NodeTargetPlugin = require('webpack/lib/node/NodeTargetPlugin');
+const LoaderTargetPlugin = require('webpack/lib/LoaderTargetPlugin');
+const LibraryTemplatePlugin = require('webpack/lib/LibraryTemplatePlugin');
+const SingleEntryPlugin = require('webpack/lib/SingleEntryPlugin');
+
+/**
+ * The HtmlWebpackChildCompiler is a helper to allow resusing one childCompiler
+ * for multile HtmlWebpackPlugin instances to improve the compilation performance.
+ */
+class HtmlWebpackChildCompiler {
+  /**
+   *
+   * @param {string[]} templates
+   */
+  constructor (templates) {
+    /**
+     * @type {string[]} templateIds
+     * The template array will allow us to keep track which input generated which output
+     */
+    this.templates = templates;
+    /**
+     * @type {Promise<{[templatePath: string]: { content: string, hash: string, entry: WebpackChunk }}>}
+     */
+    this.compilationPromise; // eslint-disable-line
+    /**
+     * @type {number}
+     */
+    this.compilationStartedTimestamp; // eslint-disable-line
+    /**
+     * @type {number}
+     */
+    this.compilationEndedTimestamp; // eslint-disable-line
+    /**
+     * All file dependencies of the child compiler
+     * @type {{fileDependencies: string[], contextDependencies: string[], missingDependencies: string[]}}
+     */
+    this.fileDependencies = { fileDependencies: [], contextDependencies: [], missingDependencies: [] };
+  }
+
+  /**
+   * Returns true if the childCompiler is currently compiling
+   * @retuns {boolean}
+   */
+  isCompiling () {
+    return !this.didCompile() && this.compilationStartedTimestamp !== undefined;
+  }
+
+  /**
+   * Returns true if the childCOmpiler is done compiling
+   */
+  didCompile () {
+    return this.compilationEndedTimestamp !== undefined;
+  }
+
+  /**
+   * This function will start the template compilation
+   * once it is started no more templates can be added
+   *
+   * @param {WebpackCompilation} mainCompilation
+   * @returns {Promise<{[templatePath: string]: { content: string, hash: string, entry: WebpackChunk }}>}
+   */
+  compileTemplates (mainCompilation) {
+    // To prevent multiple compilations for the same template
+    // the compilation is cached in a promise.
+    // If it already exists return
+    if (this.compilationPromise) {
+      return this.compilationPromise;
+    }
+
+    // The entry file is just an empty helper as the dynamic template
+    // require is added in "loader.js"
+    const outputOptions = {
+      filename: '__child-[name]',
+      publicPath: mainCompilation.outputOptions.publicPath
+    };
+    const compilerName = 'HtmlWebpackCompiler';
+    // Create an additional child compiler which takes the template
+    // and turns it into an Node.JS html factory.
+    // This allows us to use loaders during the compilation
+    const childCompiler = mainCompilation.createChildCompiler(compilerName, outputOptions);
+    // The file path context which webpack uses to resolve all relative files to
+    childCompiler.context = mainCompilation.compiler.context;
+    // Compile the template to nodejs javascript
+    new NodeTemplatePlugin(outputOptions).apply(childCompiler);
+    new NodeTargetPlugin().apply(childCompiler);
+    new LibraryTemplatePlugin('HTML_WEBPACK_PLUGIN_RESULT', 'var').apply(childCompiler);
+    new LoaderTargetPlugin('node').apply(childCompiler);
+
+    // Add all templates
+    this.templates.forEach((template, index) => {
+      new SingleEntryPlugin(childCompiler.context, template, `HtmlWebpackPlugin_${index}`).apply(childCompiler);
+    });
+
+    this.compilationStartedTimestamp = new Date().getTime();
+    this.compilationPromise = new Promise((resolve, reject) => {
+      childCompiler.runAsChild((err, entries, childCompilation) => {
+        // Extract templates
+        const compiledTemplates = entries
+          ? extractHelperFilesFromCompilation(mainCompilation, childCompilation, outputOptions.filename, entries)
+          : [];
+        // Extract file dependencies
+        if (entries) {
+          this.fileDependencies = { fileDependencies: Array.from(childCompilation.fileDependencies), contextDependencies: Array.from(childCompilation.contextDependencies), missingDependencies: Array.from(childCompilation.missingDependencies) };
+        }
+        // Reject the promise if the childCompilation contains error
+        if (childCompilation && childCompilation.errors && childCompilation.errors.length) {
+          const errorDetails = childCompilation.errors.map(error => error.message + (error.error ? ':\n' + error.error : '')).join('\n');
+          reject(new Error('Child compilation failed:\n' + errorDetails));
+          return;
+        }
+        // Reject if the error object contains errors
+        if (err) {
+          reject(err);
+          return;
+        }
+        /**
+         * @type {{[templatePath: string]: { content: string, hash: string, entry: WebpackChunk }}}
+         */
+        const result = {};
+        compiledTemplates.forEach((templateSource, entryIndex) => {
+          // The compiledTemplates are generated from the entries added in
+          // the addTemplate function.
+          // Therefore the array index of this.templates should be the as entryIndex.
+          result[this.templates[entryIndex]] = {
+            content: templateSource,
+            hash: childCompilation.hash,
+            entry: entries[entryIndex]
+          };
+        });
+        this.compilationEndedTimestamp = new Date().getTime();
+        resolve(result);
+      });
+    });
+
+    return this.compilationPromise;
+  }
+}
+
+/**
+ * The webpack child compilation will create files as a side effect.
+ * This function will extract them and clean them up so they won't be written to disk.
+ *
+ * Returns the source code of the compiled templates as string
+ *
+ * @returns Array<string>
+ */
+function extractHelperFilesFromCompilation (mainCompilation, childCompilation, filename, childEntryChunks) {
+  const helperAssetNames = childEntryChunks.map((entryChunk, index) => {
+    return mainCompilation.mainTemplate.getAssetPath(filename, {
+      hash: childCompilation.hash,
+      chunk: entryChunk,
+      name: `HtmlWebpackPlugin_${index}`
+    });
+  });
+
+  helperAssetNames.forEach((helperFileName) => {
+    delete mainCompilation.assets[helperFileName];
+  });
+
+  const helperContents = helperAssetNames.map((helperFileName) => {
+    return childCompilation.assets[helperFileName].source();
+  });
+
+  return helperContents;
+}
+
+module.exports = {
+  HtmlWebpackChildCompiler
+};

package/lib/file-watcher-api.js

@@ -0,0 +1,14 @@
+// @ts-check
+/**
+ * To use the availble webpack core api
+ * we have to use different child compilers
+ * depending on the used webpack version
+ */
+const webpackMajorVersion = Number(require('webpack/package.json').version.split('.')[0]);
+
+// Typescript hack to test only the webpack 4 code
+/** @type {import('./webpack4/file-watcher-api')} */
+module.exports = webpackMajorVersion === 4
+  ? require('./webpack4/file-watcher-api.js')
+  // Hack to ignore './webpack5/file-watcher-api.js' from typescript:
+  : require('./webpack' + 5 + '/file-watcher-api.js');

package/lib/html-tags.js

@@ -65,7 +65,31 @@ function createHtmlTagObject (tagName, attributes, innerHTML) {
   };
 }
 
+/**
+ * The `HtmlTagArray Array with a custom `.toString()` method.
+ *
+ * This allows the following:
+ * ```
+ *   const tags = HtmlTagArray.from([tag1, tag2]);
+ *   const scriptTags = tags.filter((tag) => tag.tagName === 'script');
+ *   const html = scriptTags.toString();
+ * ```
+ *
+ * Or inside a string literal:
+ * ```
+ *   const tags = HtmlTagArray.from([tag1, tag2]);
+ *   const html = `<html><body>${tags.filter((tag) => tag.tagName === 'script')}</body></html>`;
+ * ```
+ *
+ */
+class HtmlTagArray extends Array {
+  toString () {
+    return this.join('');
+  }
+}
+
 module.exports = {
+  HtmlTagArray: HtmlTagArray,
   createHtmlTagObject: createHtmlTagObject,
   htmlTagObjectToString: htmlTagObjectToString
 };

package/lib/webpack4/file-watcher-api.js

@@ -0,0 +1,64 @@
+/** @typedef {import("webpack/lib/Compilation.js")} WebpackCompilation */
+/** @typedef {{timestamp: number, fileDependencies: string[]}} Snapshot */
+'use strict';
+
+/**
+ *
+ * @param {{fileDependencies: string[], contextDependencies: string[], missingDependencies: string[]}} fileDependencies
+ * @param {WebpackCompilation} compilation
+ * @param {number} startTime
+ */
+function createSnapshot (fileDependencies, compilation, startTime) {
+  const flatDependencies = [];
+  Object.keys(fileDependencies).forEach((depencyTypes) => {
+    fileDependencies[depencyTypes].forEach(fileDependency => {
+      flatDependencies.push(fileDependency);
+    });
+  });
+  return {
+    fileDependencies: flatDependencies,
+    timestamp: startTime
+  };
+}
+
+/**
+ * Returns true if the files inside this snapshot
+ * have not been changed
+ *
+ * @param {Snapshot} snapshot
+ * @param {WebpackCompilation} compilation
+ * @returns {Promise<boolean>}
+ */
+function isSnapShotValid (snapshot, compilation) {
+  // Check if any dependent file was changed after the last compilation
+  const fileTimestamps = compilation.fileTimestamps;
+  const isCacheOutOfDate = snapshot.fileDependencies.some((fileDependency) => {
+    const timestamp = fileTimestamps.get(fileDependency);
+    // If the timestamp is not known the file is new
+    // If the timestamp is larger then the file has changed
+    // Otherwise the file is still the same
+    return !timestamp || timestamp > snapshot.timestamp;
+  });
+  return Promise.resolve(!isCacheOutOfDate);
+}
+
+/**
+ * Ensure that the files keep watched for changes
+ * and will trigger a recompile
+ *
+ * @param {WebpackCompilation} mainCompilation
+ * @param {{fileDependencies: string[], contextDependencies: string[], missingDependencies: string[]}} fileDependencies
+ */
+function watchFiles (mainCompilation, fileDependencies) {
+  Object.keys(fileDependencies).forEach((depencyTypes) => {
+    fileDependencies[depencyTypes].forEach(fileDependency => {
+      mainCompilation.compilationDependencies.add(fileDependency);
+    });
+  });
+}
+
+module.exports = {
+  createSnapshot,
+  isSnapShotValid,
+  watchFiles
+};