Updating images and fonts to use Webpack 5 Asset modules

Author: weaverryan

CHANGELOG.md

@@ -1,5 +1,38 @@
 # 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. You will notice that smaller images
+   and fonts (smaller than 8kb) will be "inlined" in CSS files instead
+   of being extracted to independent files for performance. This is
+   configurable - see the new `configureImageRule()` and `configureFontRule()`
+   methods.
+
+ * [BC BREAK] The `configureUrlLoader()` method was removed. See
+   `configureImageRule()` and `configureFontRule()` - specifically the
+   `maxSize` option. 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] 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).
+
+
 ## 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,71 @@ 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
+     *     // or javascript/auto to disable asset images (see next example)
+     *     type: 'asset',
+     *
+     *     // 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 +1617,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 +1630,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',
+            maxSize: null,
+            filename: 'images/[name].[hash:8][ext]',
+            enabled: true,
+        };
+        this.fontRuleOptions = {
+            type: 'asset',
+            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 = () => {}) {