Fix: HMR for Non-Module Systems

.changeset/angry-rockets-smash.md

@@ -0,0 +1,5 @@
+---
+"10up-toolkit": minor
+---
+
+Fix HMR for non-script module based installations and support better peer dependency management

.changeset/config.json

@@ -5,10 +5,10 @@
   "fixed": [],
   "linked": [],
   "access": "restricted",
-  "baseBranch": "trunk",
+  "baseBranch": "develop",
   "updateInternalDependencies": "patch",
   "___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH": {
     "onlyUpdatePeerDependentsWhenOutOfRange": true
   },
   "ignore": ["tenup-theme", "@10up/component-accordion", "@10up/library-ts-test"]
-}
+}

packages/toolkit/README.md

@@ -43,9 +43,27 @@ npm install --save-dev 10up-toolkit
 If you're using a version of NPM lower than 7 and `10up-toolkit` from version `4.0.0` you'll also need to install the following dependencies manually:
 
 ```bash{showPrompt}
-npm install --save-dev stylelint @10up/stylelint-config @10up/eslint-config @10up/babel-preset-default
+npm install --save-dev stylelint @10up/stylelint-config @10up/eslint-config @10up/babel-preset-default webpack-dev-server
 ```
 
+#### Upgrading the toolkit
+
+When you upgrade `10up-toolkit`, the lock file (`package-lock.json` or `yarn.lock`) may keep an older version of transitive dependencies such as `webpack-dev-server`. If you use the dev server or hot reload and see issues after upgrading, ensure a matching version is installed:
+
+```bash{showPrompt}
+npm update webpack-dev-server
+```
+
+Or reinstall from a clean state:
+
+```bash{showPrompt}
+rm -rf node_modules package-lock.json && npm install
+```
+
+The toolkit declares `webpack-dev-server` as a peer dependency so that your project’s dependency tree controls the version and upgrades are predictable when you run `npm install` after bumping the toolkit (npm 7+ installs peer dependencies automatically).
+
+**Scenarios where an older version can still be used:** Installing with `npm install --legacy-peer-deps` skips peer dependency installation and conflict checks, so an older or transitive copy of `webpack-dev-server` may be used. Pinning an old version in your own `package.json` or having another dependency that depends on an older `webpack-dev-server` can also leave an incompatible version in the tree. In those cases the toolkit will print a warning at runtime; install a matching version (e.g. `webpack-dev-server@^5.2.2`) in your project to clear it.
+
 ### Setting it up
 
 In order to get `10up-toolkit` up and running simply define the `source` and `main` properties in your `package.json` file.

packages/toolkit/config/__tests__/__snapshots__/webpack-fast-refresh.js.snap

@@ -18,13 +18,14 @@ exports[`webpack.config.js includes react-webpack-fast-refresh with the --hot op
     },
     "hot": true,
     "port": 8000,
-    "proxy": {
-      "/dist": {
+    "proxy": [
+      {
+        "context": "/dist",
         "pathRewrite": {
           "^/dist": "",
         },
       },
-    },
+    ],
   },
   "devtool": "source-map",
   "entry": "() => getEntryPoints({

packages/toolkit/config/webpack.config.js

@@ -3,8 +3,10 @@
  */
 const {
 	getBuildFiles,
+	getInstalledPackageVersion,
 	getTenUpScriptsConfig,
 	getTenUpScriptsPackageBuildConfig,
+	isMinimumPackageVersion,
 } = require('../utils');
 const { getModuleBuildFiles } = require('../utils/config');
 
@@ -42,6 +44,21 @@ const defaultTargets = [
 	'not ie_mob <=11',
 ];
 
+const MIN_WDS_VERSION = '5.2.2';
+const isHotReloadEnabled = projectConfig.devServer || projectConfig.hot;
+const isTestEnv = typeof process.env.JEST_WORKER_ID !== 'undefined';
+const webpackDevServerVersion = getInstalledPackageVersion('webpack-dev-server', '0');
+const useLegacyProxy = !isMinimumPackageVersion(webpackDevServerVersion, MIN_WDS_VERSION);
+
+if (isHotReloadEnabled && useLegacyProxy && !isTestEnv) {
+	// eslint-disable-next-line no-console -- runtime warning for incompatible peer
+	console.warn(
+		`[10up-toolkit] webpack-dev-server ${webpackDevServerVersion} was resolved; ${MIN_WDS_VERSION} or newer is recommended.\n` +
+			'  If you used --legacy-peer-deps or have an older version in your tree, install a matching version:\n' +
+			`  npm install --save-dev webpack-dev-server@${MIN_WDS_VERSION}`,
+	);
+}
+
 const config = {
 	projectConfig,
 	packageConfig,
@@ -51,6 +68,7 @@ const config = {
 	mode,
 	isProduction,
 	defaultTargets,
+	useLegacyProxy,
 };
 
 const baseConfig = {

packages/toolkit/config/webpack/__tests__/devServer.js

@@ -1,4 +1,5 @@
 const externals = require('../externals');
+const getDevServer = require('../devServer');
 
 describe('externals module function', () => {
 	it('returns default externals for project config', () => {
@@ -57,3 +58,70 @@ describe('externals module function', () => {
 		});
 	});
 });
+
+describe('devServer', () => {
+	const baseHotOptions = {
+		isPackage: false,
+		isModule: false,
+		projectConfig: {
+			devServer: false,
+			devURL: 'http://example.test',
+			hot: true,
+			devServerPort: 3000,
+		},
+	};
+
+	it('returns undefined when neither devServer nor hot is enabled', () => {
+		expect(
+			getDevServer({
+				...baseHotOptions,
+				projectConfig: { ...baseHotOptions.projectConfig, hot: false },
+			}),
+		).toBeUndefined();
+		expect(
+			getDevServer({
+				isPackage: false,
+				isModule: false,
+				projectConfig: {
+					devServer: false,
+					devURL: 'http://example.test',
+					hot: false,
+					devServerPort: 3000,
+				},
+			}),
+		).toBeUndefined();
+	});
+
+	it('uses array-based proxy configuration (v5 style) when useLegacyProxy is false', () => {
+		const result = getDevServer({ ...baseHotOptions, useLegacyProxy: false });
+		expect(result).toBeDefined();
+		expect(result.proxy).toEqual([
+			{
+				context: '/dist',
+				pathRewrite: {
+					'^/dist': '',
+				},
+			},
+		]);
+	});
+
+	it('uses array-based proxy configuration (v5 style) when useLegacyProxy is omitted', () => {
+		const result = getDevServer(baseHotOptions);
+		expect(result).toBeDefined();
+		expect(Array.isArray(result.proxy)).toBe(true);
+		expect(result.proxy[0]).toHaveProperty('context', '/dist');
+		expect(result.proxy[0].pathRewrite).toEqual({ '^/dist': '' });
+	});
+
+	it('uses object-based proxy configuration (legacy style) when useLegacyProxy is true', () => {
+		const result = getDevServer({ ...baseHotOptions, useLegacyProxy: true });
+		expect(result).toBeDefined();
+		expect(result.proxy).toEqual({
+			'/dist': {
+				pathRewrite: {
+					'^/dist': '',
+				},
+			},
+		});
+	});
+});

packages/toolkit/config/webpack/devServer.js

@@ -2,6 +2,7 @@ module.exports = ({
 	isPackage,
 	isModule,
 	projectConfig: { devServer, devURL, hot, devServerPort },
+	useLegacyProxy = false,
 }) => {
 	if (!devServer && !hot) {
 		return undefined;
@@ -23,6 +24,23 @@ module.exports = ({
 			// do nothing
 		}
 
+		const distProxyConfiguration = [
+			{
+				context: '/dist',
+				pathRewrite: {
+					'^/dist': '',
+				},
+			},
+		];
+		const legacyProxyConfiguration = {
+			'/dist': {
+				pathRewrite: {
+					'^/dist': '',
+				},
+			},
+		};
+		const proxy = useLegacyProxy ? legacyProxyConfiguration : distProxyConfiguration;
+
 		return {
 			devMiddleware: {
 				writeToDisk: true,
@@ -37,13 +55,7 @@ module.exports = ({
 				},
 			},
 			port: Number(devServerPort),
-			proxy: {
-				'/dist': {
-					pathRewrite: {
-						'^/dist': '',
-					},
-				},
-			},
+			proxy,
 		};
 	}
 

packages/toolkit/package.json

@@ -69,7 +69,6 @@
 		"url-loader": "^4.1.1",
 		"webpack": "^5.89.0",
 		"webpack-bundle-analyzer": "^4.10.1",
-		"webpack-dev-server": "^5.2.2",
 		"webpack-sources": "^3.2.3",
 		"webpackbar": "^6.0.0",
 		"yaml": "^2.4.1"
@@ -85,7 +84,8 @@
 		"@10up/stylelint-config": ">=3.0.0",
 		"@linaria/babel-preset": ">=4.3.3",
 		"@linaria/webpack-loader": ">=4.1.11",
-		"typescript": ">=5.0.0"
+		"typescript": ">=5.0.0",
+		"webpack-dev-server": "^5.2.2"
 	},
 	"peerDependenciesMeta": {
 		"@linaria/webpack-loader": {

packages/toolkit/utils/index.js

@@ -28,7 +28,14 @@ const {
 } = require('./config');
 const { fromProjectRoot, fromConfigRoot, hasProjectFile } = require('./file');
 
-const { hasPackageProp, getPackagePath, getPackage, getPackageVersion } = require('./package');
+const {
+	getInstalledPackageVersion,
+	getPackage,
+	getPackagePath,
+	getPackageVersion,
+	hasPackageProp,
+	isMinimumPackageVersion,
+} = require('./package');
 
 const { displayWebpackStats } = require('./webpack');
 
@@ -63,6 +70,7 @@ module.exports = {
 	getJestOverrideConfigFile,
 	hasJestConfig,
 	getEnvironmentFromBranch,
+	getInstalledPackageVersion,
 	hasPackageProp,
 	hasPrettierConfig,
 	hasEslintConfig,
@@ -79,6 +87,7 @@ module.exports = {
 	getTenUpScriptsPackageBuildConfig,
 	hasWebpackConfig,
 	displayWebpackStats,
+	isMinimumPackageVersion,
 	transformBlockJson,
 	getGitBranch,
 };

packages/toolkit/utils/package.js

@@ -38,6 +38,25 @@ const getPackageVersion = async () => {
 	return pkg.version;
 };
 
+/**
+ * Returns the version of an installed npm package by name.
+ * Resolves the package's package.json so it works without importing the package.
+ * Uses read-pkg to read and parse the package.json.
+ *
+ * @param {string} packageName - The name of the npm package (e.g. 'webpack-dev-server').
+ * @param {string} [fallback='0'] - Value to return if the package is not installed or version is unreadable.
+ * @returns {string} The package version string or the fallback.
+ */
+const getInstalledPackageVersion = (packageName, fallback = '0') => {
+	try {
+		const pkgPath = require.resolve(`${packageName}/package.json`);
+		const pkg = readPkg.sync({ cwd: path.dirname(pkgPath) });
+		return typeof pkg.version === 'string' ? pkg.version : fallback;
+	} catch {
+		return fallback;
+	}
+};
+
 /**
  * Checks whether the passed package name is installed in the project.
  *
@@ -55,10 +74,38 @@ const isPackageInstalled = (packageName) => {
 	return false;
 };
 
+/**
+ * Compares two semver-like version strings (e.g. "5.2.2", "1.0.0-beta.1").
+ * Only the numeric segments are compared; non-numeric segments are treated as 0.
+ *
+ * @param {string} actual - The resolved version (e.g. from a package).
+ * @param {string} min   - The minimum required version.
+ * @returns {boolean} True if actual >= min, false otherwise.
+ */
+const isMinimumPackageVersion = (actual, min) => {
+	const actualVersions = actual.split('.').map(Number);
+	const minimumVersions = min.split('.').map(Number);
+
+	for (let i = 0; i < Math.max(actualVersions.length, minimumVersions.length); i++) {
+		const actualVersionLevel = actualVersions[i] || 0;
+		const minimumVersionLevel = minimumVersions[i] || 0;
+		if (actualVersionLevel > minimumVersionLevel) {
+			return true;
+		}
+		if (actualVersionLevel < minimumVersionLevel) {
+			return false;
+		}
+	}
+
+	return true;
+};
+
 module.exports = {
-	isPackageInstalled,
-	getPackagePath,
-	hasPackageProp,
+	getInstalledPackageVersion,
 	getPackage,
+	getPackagePath,
 	getPackageVersion,
+	hasPackageProp,
+	isMinimumPackageVersion,
+	isPackageInstalled,
 };