New version 5.6.0 introduce breaking changes to the plugin interface

[sorenpa]

Current behaviour 💣

I know my situation might be quite niche but I wanted to let you know of the issue.

In the company I work for we use CRA (yes we are looking to migrate to something else). We override the react-scripts mainly to enable Module Federation. As a part of this override we need to set the publicPath in the html-webpack-plugin to the same value as the PUBLIC_URL env variable.

So until reacently our override script looked like this:

const { ModuleFederationPlugin } = require("webpack").container;

const { federationConfig } = require("../../modulefederation.config.js");

const webpackConfigPath = "react-scripts/config/webpack.config";
const webpackConfig = require(webpackConfigPath);
const HtmlWebpackPlugin = require("html-webpack-plugin");

const override = (config) => {
  config.plugins.push(new ModuleFederationPlugin(federationConfig));

  // Add PUBLIC_URL to HtmlWebpackPlugin userOptions
  config.plugins = config.plugins.map((plugin) => {
    if (plugin instanceof HtmlWebpackPlugin) { 
      plugin.userOptions = {
        ...plugin.userOptions,
        publicPath: process.env.PUBLIC_URL,  // <----- THIS IS WHERE I SET THE publicPath
      };
    }
    return plugin;
  });

  config.output.publicPath = "auto";

  config.experiments = {
    topLevelAwait: true,
  };

  return config;
};

require.cache[require.resolve(webpackConfigPath)].exports = (env) =>
  override(webpackConfig(env));

module.exports = require(webpackConfigPath);

As you can see the script is setting the publicPath on the "userOptions" property of the plugin.

This has worked fine up until release 5.6.0 (that is the suspected release my react-scripts version is using ^5.5.0).

I logged the plugin using JSON.stringify and get:

{
  "userOptions": {  // <----- THIS IS WHERE I SET THE publicPath
    "inject": true,
    "template": "C:\\projects\\common\\module.federation\\investigations\\template-test\\app2\\public\\index.html"
  },
  "version": 5,
  "options": {
    "template": "C:\\projects\\common\\module.federation\\investigations\\template-test\\app2\\public\\index.html",
    "templateContent": false,
    "filename": "index.html",
    "publicPath": "auto",
    "hash": false,
    "inject": true,
    "scriptLoading": "defer",
    "compile": true,
    "favicon": false,
    "minify": "auto",
    "cache": true,
    "showErrors": true,
    "chunks": "all",
    "excludeChunks": [],
    "chunksSortMode": "auto",
    "meta": {},
    "base": false,
    "title": "Webpack App",
    "xhtml": false
  }
}

... continued in expected behaviour

Expected behaviour ☀️

When I log the plugin contents before version 5.6.0 i get:

{
  "userOptions": { // <----- THIS IS WHERE I SET THE publicPath
    "inject": true,
    "template": "C:\\projects\\common\\module.federation\\modules\\host\\public\\index.html"
  },
  "version": 5
}

So the new version adds the "options" entry.

So I guess I would expect the interface to be the same for a semver version of 5.x.x

Reproduction Example 👾

See above its a change in the plugin interface.

Fix using 5.6.0

In my case the issue can be fixed with version 5.6.0 by simply setting the publicPath on the "options" instead of the "userOptions" entry.

  // Add PUBLIC_URL to HtmlWebpackPlugin userOptions
  config.plugins = config.plugins.map((plugin) => {
    if (plugin instanceof HtmlWebpackPlugin) {
      plugin.options = {
        ...plugin.options,
        publicPath: process.env.PUBLIC_URL,
      };
    }
    return plugin;
  });
...

Environment 🖥

Node.js v18.19.0
win32 10.0.19045
npm --version 10.2.3

wepack:
-- react-scripts@5.0.1 +-- @pmmmwh/react-refresh-webpack-plugin@0.5.11 | -- webpack@5.89.0 deduped
+-- babel-loader@8.3.0
| -- webpack@5.89.0 deduped +-- css-loader@6.8.1 | -- webpack@5.89.0 deduped
+-- css-minimizer-webpack-plugin@3.4.1
| -- webpack@5.89.0 deduped +-- eslint-webpack-plugin@3.2.0 | -- webpack@5.89.0 deduped
+-- file-loader@6.2.0
| -- webpack@5.89.0 deduped +-- html-webpack-plugin@5.6.0 | -- webpack@5.89.0 deduped
+-- mini-css-extract-plugin@2.7.6
| -- webpack@5.89.0 deduped +-- postcss-loader@6.2.1 | -- webpack@5.89.0 deduped
+-- react-dev-utils@12.0.1
| -- fork-ts-checker-webpack-plugin@6.5.3 | -- webpack@5.89.0 deduped
+-- sass-loader@12.6.0
| -- webpack@5.89.0 deduped +-- source-map-loader@3.0.2 | -- webpack@5.89.0 deduped
+-- style-loader@3.3.3
| -- webpack@5.89.0 deduped +-- terser-webpack-plugin@5.3.10 | -- webpack@5.89.0 deduped
+-- webpack-dev-server@4.15.1
| +-- webpack-dev-middleware@5.3.3
| | -- webpack@5.89.0 deduped | -- webpack@5.89.0 deduped
+-- webpack-manifest-plugin@4.1.1
| -- webpack@5.89.0 deduped +-- webpack@5.89.0 -- workbox-webpack-plugin@6.6.1
`-- webpack@5.89.0 deduped

plugin:
-- react-scripts@5.0.1 -- html-webpack-plugin@5.6.0

[alexander-akait]

Hmm, in the future we want to remove userOptions and keep only options, so theoretically we could try to fix this, but I'm not sure if it's worth it because it's a rare use case, I can accept PR if you want to fix this regression

[sorenpa]

I think only having options would make a lot of sense.

I have no idea how rare my use case is, but I am guessing its not too common. The main reason I made this bug report was to inform you of the issue, and potentially aid others having a similar usage of the package.

One could argue that this change would require a major version bump to 6.0.0, since the change is not backwards compatible in my case. That is the only real issue here I think.

So other than potentially a version bump I do not see any need to change anything regarding this issue :)

[lzane]

Just spent around 2 hours debugging and fixing the issue. 😭

We had a high traffic tonight, the static material traffic which should be handle by the CDN flow directly to main server, even causing the monitoring to crash.

IMO, There definitely should NOT be any breaking changes from version 5.5.3 to 5.6.0