docs: add a note on wds v3 and webpack 5 browserslist (#283)

README.md

@@ -49,7 +49,7 @@ pnpm add -D @pmmmwh/react-refresh-webpack-plugin react-refresh
 ```
 
 The plugin depends on a package from the React team - `react-refresh`,
-so you will have to install and configure it separately as demonstrated in the [Usage](#usage) section, too.
+so you will have to install and configure it separately as demonstrated in the [Usage](#usage) section.
 
 ### TypeScript
 

docs/TROUBLESHOOTING.md

@@ -269,3 +269,21 @@ module.exports = {
   ],
 };
 ```
+
+## Webpack 5 compatibility issues with `webpack-dev-server@3`
+
+In `webpack-dev-server@3`,
+there is a bug causing it to mis-judge the runtime environment when the Webpack 5 `browserslist` target is used.
+
+It then fallbacks to thinking a non-browser target is being used,
+in turn skipping injection of the HMR runtime,
+and thus breaking downstream integrations like this plugin.
+
+To overcome this,
+you can conditionally apply the `browserslist` only in production modes in your Webpack configuration:
+
+```js
+module.exports = {
+  target: process.env.NODE_ENV !== 'production' ? 'web' : 'browserslist',
+};
+```