[16] Introduce "load strategies" to the webpack package, and update react-pointcuts to cater for dynamic import using "React.lazy".

.gitignore

@@ -3,6 +3,9 @@ npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
 
+# Test artifacts
+coverage/
+
 # Dependency directories
 node_modules/
 

docs/CHANGELOG.md

@@ -14,6 +14,22 @@ N.B. See changelogs for individual packages, where most change will occur:
 
 This log covers the [monorepo](https://en.wikipedia.org/wiki/Monorepo).
 
+## [0.10.7] - 2025-07-17
+
+### Fixed
+
+- remove `react` and `react-dom` from repo root package.json, introduced in [version 0.9.0](#090---2024-11-29)
+
+### Added
+
+- `test:unit:coverage` script
+
+### Changed
+
+- set minimum node version to 20.8 due to use of [`import.meta.resolve`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import.meta/resolve) where possible in packages / examples
+- updated to `0.11.0` of [`eslint-plugin-workspaces`](https://github.com/joshuajaco/eslint-plugin-workspaces) after [addition of ESLint9 support](https://github.com/joshuajaco/eslint-plugin-workspaces/commit/af855c3a3d8069366d4446747e91828ddf7560c6)
+  - update `eslint.config.mjs` to utilise flat config
+
 ## [0.10.6] - 2025-07-14
 
 ### Fixed

docs/README.md

@@ -51,16 +51,18 @@ The bare minimum would be injecting a plugin from the [`webpack package`](../pac
 
 Then:
 
-1. Figure out what code modules you'd like to toggle, and see if they are suitable
-2. Figure out a filesystem convention to use
+1. Figure out what code modules you'd like to toggle.
+2. Figure out a filesystem convention to use.
    - the default proposes colocating variations of base modules in `./__variants__/<feature name>/<variant name>/` folders, with filename parity for the modules themselves.
-2. Implement the [`webpack package`](../packages/webpack/docs/README.md)[^2] into your build process, via configuration of appropriate [`pointcuts`](https://en.wikipedia.org/wiki/Pointcut), targeting code modules for toggling that meet the criteria:
-   - A single, default export, that is a function
-   - Side-effect free (or, at least, with harmless import side-effects)
-   - Resolvable by Webpack
-3. Create a feature toggle state store, utilising the [`features package`](../packages/features/docs/README.md), or otherwise, suitable for the dynamism of your toggle type.
+3. Figure out a ["loading strategy"](../packages/webpack/docs/README.md#loadstrategy) to use.
+   - the default loads modules at the point they are selected for use, and the code is build into the entry point of the application.
+   - static (loaded at the entrypoint to the bundle holding the code) or asynchronous (code split) strategies are also available, if compatible with the referring code
+4. Implement the [`webpack package`](../packages/webpack/docs/README.md)[^2] into your build process, via configuration of appropriate [`pointcuts`](https://en.wikipedia.org/wiki/Pointcut), targeting code modules for toggling that meet the criteria:
+   - A single, default export, that is a function.
+   - Resolvable by Webpack.
+5. Create a feature toggle state store, utilising the [`features package`](../packages/features/docs/README.md), or otherwise, suitable for the dynamism of your toggle type.
    - This needs to get state from an appropriate Toggle Router / runtime state provider.
-4. Create a toggle point for the point cuts
+6. Create a toggle point for the point cuts.
    - For a [React](https://react.dev/) application, the `withTogglePointFactory` or `withToggledHookFactory` from the [`react pointcuts package`](../packages/react-pointcuts/docs/README.md) can be used, to construct one.
     - Again, use [the examples](../examples/README.md) as a guide.
 

eslint.config.mjs

@@ -2,19 +2,13 @@ import asosConfig from "./peripheral/eslint-config-asosconfig/index.js";
 import globals from "globals";
 import jsdoc from "eslint-plugin-jsdoc";
 import markdown from "@eslint/markdown";
-import { FlatCompat } from "@eslint/eslintrc";
-import path from "path";
-import { fileURLToPath } from "url";
+import workspaces from "eslint-plugin-workspaces";
 
 const scripts = ["*.{js,mjs}", "**/*.{js,mjs}"];
 const markDowns = ["*.md", "**/*.md"];
 
-const compat = new FlatCompat({
-  baseDirectory: path.dirname(fileURLToPath(import.meta.url))
-});
-
 export default [
-  ...compat.extends("plugin:workspaces/recommended"),
+  workspaces.configs["flat/recommended"],
   ...asosConfig.map((config) => ({
     files: scripts,
     ignores: ["**/docs/**", "**/danger/**"],

examples/express/docs/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2025-05-17
+
+### Changed
+
+- added `source-map` devtool and `source-map-loader` to add in visualisation of the module structure in browser developer tools
+- fixed to exact version of `react` in `dependencies`, and brought in version-linked `react-is`, a new required peer dependency of the `react-pointcuts` package
+- updated the `config` example to utilise the `lazyComponentLoadStrategyFactory` from the `react-pointcuts` package
+- updated the `animals` example to utilise the `staticLoadStrategyFactory` from the `webpack` package
+- updated `webpack` to `5.99.7`
+- update to support new object argument for toggle points introduced by updated webpack plugin
+- `MiniCssExtractPlugin` moved to "common" setup block when configuring point cut
+- updated to use [`output.module`](https://webpack.js.org/configuration/output/#outputmodule), to help demonstrate this compatibility
+  - updated [`webpack-node-externals`](https://www.npmjs.com/package/webpack-node-externals) to use `module` [`importType`](https://www.npmjs.com/package/webpack-node-externals#optionsimporttype-commonjs)
+
+### Fixed
+
+- removed "Vary" header from "animals" example, the page is meant to be un-cacheable, and the value was wrong in any case
+
 ## [0.2.5] - 2025-05-27
 
 ### Changed

examples/express/package.json

@@ -1,6 +1,6 @@
 {
   "name": "web-toggle-point-express-example",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "type": "module",
   "engines": {
     "node": ">=20.6.0"
@@ -10,25 +10,27 @@
     "build-dependencies": "path-exists ../../packages/webpack/lib || npm run --prefix ../../packages/webpack build && path-exists ../../packages/ssr/lib || npm run --prefix ../../packages/ssr build && path-exists ../../packages/features/lib || npm run --prefix ../../packages/features build && path-exists ../../packages/react-pointcuts/lib || npm run --prefix ../../packages/react-pointcuts build",
     "prebuild": "npm run build-dependencies",
     "build": "webpack",
-    "start": "cross-env PORT=3002 node bin/server.cjs",
-    "start:small-env": "cross-env PORT=3003 node --env-file=./src/routes/config/.env-small bin/server.cjs",
-    "start:large-env": "cross-env PORT=3004 node --env-file=./src/routes/config/.env-large bin/server.cjs",
+    "start": "cross-env PORT=3002 node bin/server.mjs",
+    "start:small-env": "cross-env PORT=3003 node --env-file=./src/routes/config/.env-small bin/server.mjs",
+    "start:large-env": "cross-env PORT=3004 node --env-file=./src/routes/config/.env-large bin/server.mjs",
     "prelint": "npm run build-dependencies",
     "lint": "npm run lint:code && npm run lint:docs",
     "lint:fix": "npm run lint:code -- --fix && npm run lint:docs -- --fix",
     "lint:code": "eslint src --flag unstable_config_lookup_from_file",
     "lint:docs": "eslint *.md --flag unstable_config_lookup_from_file"
   },
   "dependencies": {
-    "@asos/web-toggle-point-react-pointcuts": "file:../../packages/react-pointcuts",
     "@asos/web-toggle-point-features": "file:../../packages/features",
+    "@asos/web-toggle-point-react-pointcuts": "file:../../packages/react-pointcuts",
     "@asos/web-toggle-point-ssr": "file:../../packages/ssr",
     "@asos/web-toggle-point-webpack": "file:../../packages/webpack",
     "cross-env": "^7.0.3",
     "express": "^4.17.1",
     "http-status-codes": "^2.3.0",
-    "react": ">=17",
-    "react-dom": ">=17"
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-is": "^18.3.1",
+    "source-map-loader": "^5.0.0"
   },
   "devDependencies": {
     "babel-loader": "^9.2.1",
@@ -37,7 +39,7 @@
     "path-exists-cli": "^2.0.0",
     "prop-types": "^15.7.2",
     "style-loader": "^4.0.0",
-    "webpack": "^5.38.1",
+    "webpack": "^5.99.7",
     "webpack-cli": "^4.7.2",
     "webpack-node-externals": "^3.0.0"
   },

examples/express/src/index.js

@@ -37,7 +37,7 @@ app.get("/", (_, response) => {
   </head>
   <body>
     <ul>
-      <li><a href="/animals">Version header with nodeRequestScoped store</a></li>
+      <li><a href="/animals">Version header with nodeRequestScoped features store</a></li>
       <li><a href="/config">.env config with ssrBackedReactContext store for initial value in browser</a></li>
     </ul>
   </body>

examples/express/src/routes/animals/README.md

@@ -19,7 +19,11 @@ It also demonstrates the addition of a toggle-specific side-effect, resulting in
 
 You should see a picture of a cat or a dog, depending on the version chosen.  The contrived application uses a `streamImage` module that accesses a `urlFetcher`, which is varied by the toggle point.
 
-The toggle point is a higher-order function to ensure that each invocation honours the toggle decision, based on current context.  As a caveat of toggling, the constructor of the `urlFetcher` must be called on each request, rather than statically enacted at application start-up.  The code demonstrates a mitigation of hypothetical cost of re-construction via use of a cache within the toggle point.
+## Implementation
+
+The variant module loading mode is configured as `static`, meaning all variations are added to the module instance cache when the application starts. 
+
+The toggle point is a higher-order function to ensure that each invocation honours the toggle decision, based on current context, forwarding on arguments to a class constructor.  As a caveat of `static` toggling, the constructor of the `urlFetcher` must be called on each request, rather than statically enacted at application start-up.  The code demonstrates a mitigation of hypothetical cost of re-construction via use of a cache within the toggle point.
 The toggle point wraps the varied modules in a [`Proxy`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy/Proxy) to add the logging side-effect.
 
 The use of [AsyncLocalStorage](https://nodejs.org/api/async_context.html#class-asynclocalstorage) allows the toggle decision to be scoped on a per-request basis, without explicit access to the express request context.  The storage is initialised within [middleware](https://expressjs.com/en/resources/middleware.html).

examples/express/src/routes/animals/featuresStore.js

@@ -1,4 +1,4 @@
-import { nodeRequestScopedStoreFactory as featuresStoreFactory } from "@asos/web-toggle-point-features";
+import { nodeRequestScopedFeaturesStoreFactory as featuresStoreFactory } from "@asos/web-toggle-point-features";
 
 const featuresStore = featuresStoreFactory();
 

examples/express/src/routes/animals/middleware.js

@@ -8,7 +8,6 @@ const contextMiddleware = (request, response, scopeCallBack) => {
     response.status(StatusCodes.BAD_REQUEST).end();
     return;
   }
-  response.header("Vary", version);
   featuresStore.useValue({ value: { version }, scopeCallBack });
 };
 

examples/express/src/routes/animals/togglePoint.js

@@ -2,7 +2,7 @@ import featuresStore from "./featuresStore.js";
 
 const cache = new WeakMap();
 
-export default (_, featuresMap) => {
+export default ({ featuresMap }) => {
   return function (...args) {
     const { default: Choice } = featuresMap.get(
       `v${featuresStore.getFeatures().version}`

examples/express/src/routes/config/README.md

@@ -8,12 +8,19 @@ It shows how a payload can be included in the props passed to the toggle point c
 
 N.B. No implication that this is in any way a _good use_ of "config", it's heavily contrived.
 
+The implementation uses the `lazyComponentLoadStrategyFactory` from the `react-pointcuts` package, to ensure that variant code is bundled independently, and downloaded on demand.
+
 ## Setup
 
 1. `npm install`
 2. `npm run start`
 3. open `localhost:3002/config` in a browser, you should see a medium sized div
 4. stop, and re-start the server with `npm run start:small-env` or `npm run start:large-env`
 5. open `localhost:3003/config` (small env) or `localhost:3004/config` (large env), and see a different sized (and coloured) `div` shown
-6. press the buttons, to demonstrate overriding the initial content serialized on the server.
+6. press the buttons, to demonstrate overriding the initial content serialized on the server
    - N.B. The colourisation is only a result of the stored config, so using the buttons will just change the size
+   - watch the network tab in developer tools to observe the lazy loading in effect
+   - try blocking one of the subsequent chunks, you should see the error boundary falling back to the default experience, with a console log:
+     ```
+     ChunkLoadError: Variant errored, rendering fallback: Loading chunk ### failed.
+     ```

examples/express/src/routes/config/router.js

@@ -31,7 +31,7 @@ router.get("/*", (req, res) => {
       </body>
     </html>,
     {
-      bootstrapScripts: ["/config/main.js"],
+      bootstrapModules: ["/config/main.mjs"],
       onShellReady() {
         res.statusCode = 200;
         res.setHeader("Content-type", "text/html");

examples/express/webpack.config.js

@@ -1,81 +1,105 @@
 import { resolve, basename, dirname, posix } from "path";
+import { fileURLToPath } from "url";
 import externals from "webpack-node-externals";
-import { TogglePointInjection } from "@asos/web-toggle-point-webpack/plugins";
+import { TogglePointInjectionPlugin } from "@asos/web-toggle-point-webpack/plugins";
 import MiniCssExtractPlugin from "mini-css-extract-plugin";
-import { fileURLToPath } from "url";
+import staticLoadStrategyFactory from "@asos/web-toggle-point-webpack/moduleLoadStrategyFactories/staticLoadStrategyFactory";
+import lazyComponentLoadStrategyFactory from "@asos/web-toggle-point-react-pointcuts/lazyComponentLoadStrategyFactory";
 
 const configPointCutConfig = {
   name: "configuration variants",
   variantGlobs: ["./src/routes/config/__variants__/*/*/*.jsx"],
-  togglePointModule: "/src/routes/config/togglePoint.js"
+  togglePointModuleSpecifier: "/src/routes/config/togglePoint.js",
+  loadStrategy: lazyComponentLoadStrategyFactory(),
 };
 
 const common = {
   mode: "production",
+  devtool: "source-map",
+  experiments: {
+    outputModule: true,
+  },
+  output: {
+    module: true,
+  },
   module: {
     rules: [
       {
         test: /\.jsx?$/,
         exclude: /node_modules/,
         use: {
-          loader: "babel-loader"
-        }
+          loader: "babel-loader",
+        },
       },
       {
         test: /\.css$/,
-        use: [MiniCssExtractPlugin.loader, "css-loader"]
-      }
-    ]
-  }
+        use: [MiniCssExtractPlugin.loader, "css-loader"],
+      },
+    ],
+  },
+  plugins: [new MiniCssExtractPlugin()],
 };
 
 const config = [
   {
     entry: "./src/index.js",
     target: "node",
+    ...common,
     output: {
+      ...common.output,
       path: resolve(dirname(fileURLToPath(import.meta.url)), "bin"),
-      filename: "server.cjs",
+      filename: "server.mjs",
       clean: true,
-      chunkFormat: "module"
     },
-    externals: [externals()],
-    ...common,
+    externals: [externals({ importType: "module" })],
     plugins: [
-      new MiniCssExtractPlugin(),
-      new TogglePointInjection({
+      ...common.plugins,
+      new TogglePointInjectionPlugin({
         pointCuts: [
           configPointCutConfig,
           {
             name: "animal apis by version",
             variantGlobs: [
-              "./src/routes/animals/api/**/v{1..9}*([[:digit:]])/*.js"
+              "./src/routes/animals/api/**/v{1..9}*([[:digit:]])/*.js",
             ],
             joinPointResolver: (variantPath) =>
               posix.resolve(
                 variantPath,
                 ...Array(3).fill(".."),
                 basename(variantPath)
               ),
-            togglePointModule: "/src/routes/animals/togglePoint.js"
-          }
-        ]
-      })
-    ]
+            togglePointModuleSpecifier: "/src/routes/animals/togglePoint.js",
+            loadStrategy: staticLoadStrategyFactory(),
+          },
+        ],
+      }),
+    ],
   },
   {
     entry: "./src/routes/config/client.js",
     target: "web",
+    ...common,
     output: {
+      ...common.output,
       path: resolve(dirname(fileURLToPath(import.meta.url)), "public"),
-      filename: "main.js"
+      filename: "main.mjs",
     },
     plugins: [
-      new MiniCssExtractPlugin(),
-      new TogglePointInjection({ pointCuts: [configPointCutConfig] })
+      ...common.plugins,
+      new TogglePointInjectionPlugin({ pointCuts: [configPointCutConfig] }),
     ],
-    ...common
-  }
+    module: {
+      ...common.module,
+      rules: [
+        {
+          test: /\.js$/,
+          enforce: "pre",
+          use: ["source-map-loader"],
+        },
+        ...common.module.rules,
+      ],
+    },
+  },
 ];
 
 export default config;