feature #883 Updating images and fonts to use Webpack 5 Asset modules (weaverryan)

This PR was squashed before being merged into the main branch.

Discussion
----------

Updating images and fonts to use Webpack 5 Asset modules

This is one more big piece for proper Webpack 5 support - see #880

This also updates the CHANGELOG both for this PR and for the original in #645

And, this adds a new assertion method that helps check directory contents in functional.js in a way that is more resilient to hash changes.

For the most part... this just worked! See the CHANGELOG. Because this will release on 1.0, I have decided to remove a few methods instead of deprecating them ).

Cheers!

Commits
-------

55495cf changing the default to asset/resource
a663fbc moving require into loader function
8d3b401 fixing tests on the lowest deps due to version upgrades
3e9c787 Making tests more resilient to failure by fuzzy checking some hash filenames
d86e115 upgrading Webpack min
64c6c2f updating CHANGELOG for original Webpack 5 changes in #645
16c0f12 Updating images and fonts to use Webpack 5 Asset modules

Author: weaverryan

CHANGELOG.md

@@ -1,5 +1,56 @@
 # CHANGELOG
 
+## 1.0.0
+
+ * [DEPENDENCY UPGRADE] Webpack was upgraded from version 4 to 5.
+
+ * [BC BREAK] Image and font processing was changed from using `file-loader`
+   (and  optionally `url-loader` via `configureUrlLoader()`) to Webpack 5's
+   new [Asset Modules](https://webpack.js.org/guides/asset-modules/).
+   In practice, unless you have a highly-configured system, this should
+   not cause significant changes.
+
+ * [BC BREAK] The `configureUrlLoader()` method was removed. See
+   `configureImageRule()` and `configureFontRule()` - specifically the
+   `maxSize` option and type: 'asset'. The `url-loader` is no longer used.
+
+ * [BC BREAK] The `disableImagesLoader()` and `disableFontsLoader()` methods
+   have been removed. See `configureImageRule()` and `configureFontRule()`
+   for a new option to disable these.
+
+ * [BC BREAK] The `configureFilenames()` method no longer accepts paths
+   for `images` or `fonts`. See `configureImageRule()` and `configureFontRule()`
+   for how to configure these filenames. The `configureFilenames()` method
+   *does* now accept an `assets` option, but out-of-the-box, this will not
+   result in any filename changes. See `configureFilenames()` for more details.
+
+* [BC BREAK] `css-minimizer-webpack-plugin` was replaced by
+  `css-minimizer-webpack-plugin` and the `optimizeCssPluginOptionsCallback()`
+  method was replaced by `cssMinimizerPluginOptionsCallback()`.
+
+* [BC BREAK] The `file-loader` package is no longer required by Encore. If
+   you use `copyFiles()`, you will need to install it manually (you
+   will receive a clear error about this).
+
+* [BC BREAK] All previously-deprecated methods & options were removed.
+
+* [DEPENDENCY UPGRADES] The following packages had major version upgrades:
+   * `css-loader` from 3 to 5
+   * `mini-css-extract-plugin` from 0.4 to 1
+   * `style-loader` from 1 to 2
+   * `terser-webpack-plugin` from 1 to 4
+   * `webpack-cli` from 3 to 4
+   * `webpack-manifest-plugin` from 2 to 3
+
+* [BEHAVIOR CHANGE] The `HashedModuleIdsPlugin` was previously used to
+  help name "modules" when building for production. This has been removed
+  and we now use Webpack's native `optimization.moduleIds` option, which
+  is set to `deterministic`.
+
+* [configureMiniCssExtractPlugin()] `configureMiniCssExtractPlugin()` was
+  added to allow the `MiniCssExtractPlugin.loader` and `MiniCssExtractPlugin`
+  to be configured.
+
 ## 0.33.0
 
  * [disableCssExtraction()] Added boolean argument to `disableCssExtraction()`

index.js

@@ -1299,30 +1299,6 @@ class Encore {
         return this;
     }
 
-    /**
-     * Call this if you wish to disable the default
-     * images loader.
-     *
-     * @returns {Encore}
-     */
-    disableImagesLoader() {
-        webpackConfig.disableImagesLoader();
-
-        return this;
-    }
-
-    /**
-     * Call this if you wish to disable the default
-     * fonts loader.
-     *
-     * @returns {Encore}
-     */
-    disableFontsLoader() {
-        webpackConfig.disableFontsLoader();
-
-        return this;
-    }
-
     /**
      * Call this if you don't want imported CSS to be extracted
      * into a .css file. All your styles will then be injected
@@ -1377,8 +1353,7 @@ class Encore {
      * Encore.configureFilenames({
      *     js: '[name].[contenthash].js',
      *     css: '[name].[contenthash].css',
-     *     images: 'images/[name].[hash:8].[ext]',
-     *     fonts: 'fonts/[name].[hash:8].[ext]'
+     *     assets: 'assets/[name].[hash:8][ext]',
      * });
      * ```
      *
@@ -1389,6 +1364,10 @@ class Encore {
      * make sure that your "js" and "css" filenames contain
      * "[contenthash]".
      *
+     * The "assets" key is used for the output.assetModuleFilename option,
+     * which is overridden for both fonts and images. See configureImageRule()
+     * and configureFontRule() to control those filenames.
+     *
      * @param {object} filenames
      * @returns {Encore}
      */
@@ -1399,30 +1378,73 @@ class Encore {
     }
 
     /**
-     * Allows to configure the URL loader.
+     * Configure how images are loaded/processed under module.rules.
+     *
+     * https://webpack.js.org/guides/asset-modules/
      *
-     * https://github.com/webpack-contrib/url-loader
+     * The most important things can be controlled by passing
+     * an options object to the first argument:
      *
      * ```
-     * Encore.configureUrlLoader({
-     *     images: {
-     *         limit: 8192,
-     *         mimetype: 'image/png'
-     *     },
-     *     fonts: {
-     *         limit: 4096
-     *     }
+     * Encore.configureImageRule({
+     *     // common values: asset, asset/resource, asset/inline
+     *     // Using "asset" will allow smaller images to be "inlined"
+     *     // instead of copied.
+     *     // javascript/auto caan be used to disable asset images (see next example)
+     *     type: 'asset/resource',
+     *
+     *     // applicable when for "type: asset": files smaller than this
+     *     // size will be "inlined" into CSS, larer files will be extracted
+     *     // into independent files
+     *     maxSize: 4 * 1024, // 4 kb
+     *
+     *     // control the output filename of images
+     *     filename: 'images/[name].[hash:8][ext]',
+     *
+     *     // you can also fully disable the image rule if you want
+     *     // to control things yourself
+     *     enabled: true,
      * });
      * ```
      *
-     * If a key (e.g. fonts) doesn't exists or contains a
-     * falsy value the file-loader will be used instead.
+     * If you need more control, you can also pass a callback to the
+     * 2nd argument. This will be passed the specific Rule object,
+     * which you can modify:
      *
-     * @param {object} urlLoaderOptions
-     * @return {Encore}
+     * https://webpack.js.org/configuration/module/#rule
+     *
+     * ```
+     * Encore.configureImageRule({}, function(rule) {
+     *     // if you set "type: 'javascript/auto'" in the first argument,
+     *     // then you can now specify a loader manually
+     *     // rule.loader = 'file-loader';
+     *     // rule.options = { filename: 'images/[name].[hash:8][ext]' }
+     * });
+     * ```
+     *
+     * @param {object} options
+     * @param {string|object|function} ruleCallback
+     * @returns {Encore}
+     */
+    configureImageRule(options = {}, ruleCallback = (rule) => {}) {
+        webpackConfig.configureImageRule(options, ruleCallback);
+
+        return this;
+    }
+
+    /**
+     * Configure how fonts are processed/loaded under module.rules.
+     *
+     * https://webpack.js.org/guides/asset-modules/
+     *
+     * See configureImageRule() for more details.
+     *
+     * @param {object} options
+     * @param {string|object|function} ruleCallback
+     * @returns {Encore}
      */
-    configureUrlLoader(urlLoaderOptions = {}) {
-        webpackConfig.configureUrlLoader(urlLoaderOptions);
+    configureFontRule(options = {}, ruleCallback = (rule) => {}) {
+        webpackConfig.configureFontRule(options, ruleCallback);
 
         return this;
     }
@@ -1597,9 +1619,10 @@ class Encore {
      *
      * @param {string} environment
      * @param {object} options
+     * @param {boolean} enablePackageJsonCheck
      * @returns {Encore}
      */
-    configureRuntimeEnvironment(environment, options = {}) {
+    configureRuntimeEnvironment(environment, options = {}, enablePackageJsonCheck = true) {
         runtimeConfig = parseRuntime(
             Object.assign(
                 {},
@@ -1609,7 +1632,7 @@ class Encore {
             process.cwd()
         );
 
-        webpackConfig = new WebpackConfig(runtimeConfig, true);
+        webpackConfig = new WebpackConfig(runtimeConfig, enablePackageJsonCheck);
 
         return this;
     }

lib/WebpackConfig.js

@@ -97,8 +97,18 @@ class WebpackConfig {
         this.useSourceMaps = false;
         this.cleanupOutput = false;
         this.extractCss = true;
-        this.useImagesLoader = true;
-        this.useFontsLoader = true;
+        this.imageRuleOptions = {
+            type: 'asset/resource',
+            maxSize: null,
+            filename: 'images/[name].[hash:8][ext]',
+            enabled: true,
+        };
+        this.fontRuleOptions = {
+            type: 'asset/resource',
+            maxSize: null,
+            filename: 'fonts/[name].[hash:8][ext]',
+            enabled: true,
+        };
         this.usePostCssLoader = false;
         this.useLessLoader = false;
         this.useStylusLoader = false;
@@ -126,10 +136,6 @@ class WebpackConfig {
         this.preactOptions = {
             preactCompat: false
         };
-        this.urlLoaderOptions = {
-            images: false,
-            fonts: false
-        };
         this.babelOptions = {
             exclude: /(node_modules|bower_components)/,
             useBuiltIns: false,
@@ -146,6 +152,8 @@ class WebpackConfig {
         };
 
         // Features/Loaders options callbacks
+        this.imageRuleCallback = () => {};
+        this.fontRuleCallback = () => {};
         this.postCssLoaderOptionsCallback = () => {};
         this.sassLoaderOptionsCallback = () => {};
         this.lessLoaderOptionsCallback = () => {};
@@ -813,14 +821,6 @@ class WebpackConfig {
         this.handlebarsConfigurationCallback = callback;
     }
 
-    disableImagesLoader() {
-        this.useImagesLoader = false;
-    }
-
-    disableFontsLoader() {
-        this.useFontsLoader = false;
-    }
-
     disableCssExtraction(disabled = true) {
         this.extractCss = !disabled;
     }
@@ -831,30 +831,54 @@ class WebpackConfig {
         }
 
         // Check allowed keys
-        const validKeys = ['js', 'css', 'images', 'fonts'];
+        const validKeys = ['js', 'css', 'assets'];
         for (const key of Object.keys(configuredFilenames)) {
             if (!validKeys.includes(key)) {
-                throw new Error(`"${key}" is not a valid key for configureFilenames(). Valid keys: ${validKeys.join(', ')}.`);
+                throw new Error(`"${key}" is not a valid key for configureFilenames(). Valid keys: ${validKeys.join(', ')}. Use configureImageRule() or configureFontRule() to control image or font filenames.`);
             }
         }
 
         this.configuredFilenames = configuredFilenames;
     }
 
-    configureUrlLoader(urlLoaderOptions = {}) {
-        if (typeof urlLoaderOptions !== 'object') {
-            throw new Error('Argument 1 to configureUrlLoader() must be an object.');
+    configureImageRule(options = {}, ruleCallback = () => {}) {
+        for (const optionKey of Object.keys(options)) {
+            if (!(optionKey in this.imageRuleOptions)) {
+                throw new Error(`Invalid option "${optionKey}" passed to configureImageRule(). Valid keys are ${Object.keys(this.imageRuleOptions).join(', ')}`);
+            }
+
+            this.imageRuleOptions[optionKey] = options[optionKey];
         }
 
-        // Check allowed keys
-        const validKeys = ['images', 'fonts'];
-        for (const key of Object.keys(urlLoaderOptions)) {
-            if (!validKeys.includes(key)) {
-                throw new Error(`"${key}" is not a valid key for configureUrlLoader(). Valid keys: ${validKeys.join(', ')}.`);
+        if (this.imageRuleOptions.maxSize && this.imageRuleOptions.type !== 'asset') {
+            throw new Error('Invalid option "maxSize" passed to configureImageRule(): this option is only valid when "type" is set to "asset".');
+        }
+
+        if (typeof ruleCallback !== 'function') {
+            throw new Error('Argument 2 to configureImageRule() must be a callback function.');
+        }
+
+        this.imageRuleCallback = ruleCallback;
+    }
+
+    configureFontRule(options = {}, ruleCallback = () => {}) {
+        for (const optionKey of Object.keys(options)) {
+            if (!(optionKey in this.fontRuleOptions)) {
+                throw new Error(`Invalid option "${optionKey}" passed to configureFontRule(). Valid keys are ${Object.keys(this.fontRuleOptions).join(', ')}`);
             }
+
+            this.fontRuleOptions[optionKey] = options[optionKey];
+        }
+
+        if (this.fontRuleOptions.maxSize && this.fontRuleOptions.type !== 'asset') {
+            throw new Error('Invalid option "maxSize" passed to configureFontRule(): this option is only valid when "type" is set to "asset".');
+        }
+
+        if (typeof ruleCallback !== 'function') {
+            throw new Error('Argument 2 to configureFontRule() must be a callback function.');
         }
 
-        this.urlLoaderOptions = urlLoaderOptions;
+        this.fontRuleCallback = ruleCallback;
     }
 
     cleanupOutputBeforeBuild(paths = ['**/*'], cleanWebpackPluginOptionsCallback = () => {}) {