feat: build thin externalization client (#852)

Author: pmmmwh

.gitignore

@@ -5,6 +5,7 @@
 
 # distribution
 *dist
+*umd
 
 # misc
 .DS_Store

CHANGELOG.md

@@ -10,6 +10,10 @@
   It was necessary to support WDS below `4.8.0` (published in April 2022),
   but is no-longer needed as a direct integration with WDS is now possible.
 
+### Features
+
+- Added helper script to better support use cases where React and/or React-DOM are externalized (#852)
+
 ## 0.5.16 (31 Mar 2025)
 
 ### Fixes

docs/TROUBLESHOOTING.md

@@ -268,9 +268,21 @@ but do note that React DevTools does not inject hooks over a frame boundary (`if
 **Externalise React Refresh**
 
 If all solutions above are not applicable, you can also externalise `react-refresh/runtime` together with React.
+We provide an entrypoint to easily achieve this - `@pmmmwh/react-refresh-webpack-plugin/umd/client.min.js`.
 
-Using this, however, would require you to ensure the injected entry from this plugin is executed before React.
-You can check out [this sandbox](https://codesandbox.io/s/react-refresh-externals-14fpn) for an example on how this could be done.
+If you would like to use the provided script, ensure that it is loaded before React and/or React-DOM.
+You can load this script via any CDN for `npm`, such as `jsDelivr` and `unpkg`:
+
+```html
+<!-- if you prefer jsDelivr -->
+<script src=" https://cdn.jsdelivr.net/npm/@pmmmwh/react-refresh-webpack-plugin@^0.6.0/umd/client.min.js "></script>
+
+<!-- if you prefer unpkg -->
+<script src="https://unpkg.com/@pmmmwh/react-refresh-webpack-plugin@^0.6.0/umd/client.min.js"></script>
+```
+
+If you don't want to use the provided script,
+you can check out [this sandbox](https://codesandbox.io/s/react-refresh-externals-14fpn) for an example on how this could be done manually.
 
 ## Running multiple instances of React Refresh simultaneously
 

package.json

@@ -34,7 +34,8 @@
     "options",
     "overlay",
     "sockets",
-    "types"
+    "types",
+    "umd"
   ],
   "packageManager": "[email protected]+sha1.ac34549e6aa8e7ead463a7407e1c7390f61a6610",
   "scripts": {
@@ -54,8 +55,9 @@
     "types:clean": "rimraf types",
     "types:compile": "tsc -p tsconfig.json",
     "types:prune-private": "del \"types/*/*\" \"!types/{lib,loader,options}/{index,types}.d.ts\"",
-    "generate-types": "run-s types:clean types:compile types:prune-private \"format --loglevel silent\"",
-    "prepublishOnly": "yarn generate-types"
+    "generate:client-external": "webpack",
+    "generate:types": "run-s types:clean types:compile types:prune-private \"format --log-level silent\"",
+    "prepublishOnly": "run-p generate:*"
   },
   "dependencies": {
     "ansi-html": "^0.0.9",
@@ -97,6 +99,7 @@
     "puppeteer": "^22.10.0",
     "react-refresh": "^0.14.2",
     "sourcemap-validator": "^2.1.0",
+    "terser-webpack-plugin": "^5.3.10",
     "type-fest": "^4.18.3",
     "typescript": "~5.4.5",
     "webpack": "^5.94.0",

webpack.config.js

@@ -0,0 +1,25 @@
+const path = require('node:path');
+const TerserPlugin = require('terser-webpack-plugin');
+
+module.exports = {
+  mode: 'production',
+  entry: {
+    client: './client/ReactRefreshEntry.js',
+  },
+  optimization: {
+    minimize: true,
+    minimizer: [
+      new TerserPlugin({
+        extractComments: false,
+        terserOptions: {
+          format: { comments: false },
+        },
+      }),
+    ],
+    nodeEnv: 'development',
+  },
+  output: {
+    filename: '[name].min.js',
+    path: path.resolve(__dirname, 'umd'),
+  },
+};