fix(gatsby): show @hot-loader installation prompt

dictionary.txt

@@ -560,6 +560,7 @@ Dodds
 Doggo
 DOM
 DOMPurify
+dom
 doopoll
 dotenv
 doubleBind
@@ -964,6 +965,7 @@ Hexo
 hinzufügen
 HIPAA
 Hmmm
+HMR
 HOC
 HOCs
 Holík

docs/docs/troubleshooting-common-errors.md

@@ -256,3 +256,27 @@ echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo s
 ```
 
 You may be able to find more information for your circumstances in [the GitHub issue corresponding to this error](https://github.com/gatsbyjs/gatsby/issues/11406).
+
+## Errors during development
+
+### React-Hot-Loader: react-🔥-dom patch is not detected. React 16.6+ features may not work.
+
+`gatsby develop` uses Hot Module Replacement (HMR) to update your webpage without refreshing the page. The package that Gatsby uses for HMR is [react-hot-loader](https://github.com/gaearon/react-hot-loader). When opening the console, you might see the following warning:
+
+```shell
+React-Hot-Loader: react-🔥-dom patch is not detected. React 16.6+ features may not work.
+```
+
+To make sure all React features work, you'll have to install `@hot-loader/react-dom`. It's a patched version of the original `react-dom` package that makes [React Hooks](https://reactjs.org/docs/hooks-intro.html) work with HMR. When not available, changes made in a file that contains a React hook will do a forced browser refresh instead of a hot module update.
+
+You have to make sure the installed version of `@hot-loader/react-dom` is the same as your `react-dom` version. For example, if `react-dom` is at version 16.13.0, you'll have to install `@hot-loader/[email protected]`. In this case, you would see the following message in your CLI:
+
+```shell
+warning React-Hot-Loader: please install "@hot-loader/[email protected]" to make sure all features of React are working.
+```
+
+To resolve this message, install the matching version of `@hot-loader/react-dom` using `npm install` (or its Yarn equivalent, `yarn add`):
+
+```shell
+npm install @hot-loader/[email protected]
+```

packages/gatsby/src/utils/webpack.config.js

@@ -17,6 +17,7 @@ const apiRunnerNode = require(`./api-runner-node`)
 import { createWebpackUtils } from "./webpack-utils"
 import { hasLocalEslint } from "./local-eslint-config-finder"
 import { getAbsolutePathForVirtualModule } from "./gatsby-webpack-virtual-modules"
+import semver from "semver"
 
 const FRAMEWORK_BUNDLES = [`react`, `react-dom`, `scheduler`, `prop-types`]
 
@@ -164,11 +165,14 @@ module.exports = async (
         return {
           polyfill: directoryPath(`.cache/polyfill-entry`),
           commons: [
+            process.env.GATSBY_HOT_LOADER === `fast-refresh`
+              ? `react-hot-loader/patch`
+              : null,
             `${require.resolve(
               `webpack-hot-middleware/client`
             )}?path=${getHmrPath()}`,
             directoryPath(`.cache/app`),
-          ],
+          ].filter(Boolean),
         }
       case `develop-html`:
         return {
@@ -324,19 +328,6 @@ module.exports = async (
           },
         ])
 
-        // RHL will patch React, replace React-DOM by React-🔥-DOM and work with fiber directly
-        // It's necessary to remove the warning in console (https://github.com/gatsbyjs/gatsby/issues/11934)
-        // TODO: Remove entire block when we make fast-refresh the default
-        if (process.env.GATSBY_HOT_LOADER !== `fast-refresh`) {
-          configRules.push({
-            include: /node_modules\/react-dom/,
-            test: /\.jsx?$/,
-            use: {
-              loader: require.resolve(`./webpack-hmr-hooks-patch`),
-            },
-          })
-        }
-
         break
       }
       case `build-html`:
@@ -423,6 +414,28 @@ module.exports = async (
       ],
     }
 
+    // if react-hot-reloading
+    if (
+      stage === `develop` &&
+      process.env.GATSBY_HOT_LOADER !== `fast-refresh`
+    ) {
+      resolve.alias[`react-hot-loader`] = path.dirname(
+        require.resolve(`react-hot-loader/package.json`)
+      )
+
+      // We need to add @hot-loader/react-dom to support hot-loader work with hooks
+      try {
+        resolve.alias[`react-dom/server$`] = require.resolve(`react-dom/server`)
+        resolve.alias[`react-dom`] = require.resolve(`@hot-loader/react-dom`)
+      } catch (err) {
+        const { version: reactDomVersion } = require(`react-dom/package.json`)
+        const { major, minor } = semver.parse(reactDomVersion)
+        console.warn(
+          `React-Hot-Loader: please install "@hot-loader/react-dom@${major}.${minor}" to make sure all features of React are working.`
+        )
+      }
+    }
+
     const target =
       stage === `build-html` || stage === `develop-html` ? `node` : `web`
     if (target === `web`) {