docs(hmr): improve handleHotUpdate and add further reading (#15996)

Author: bluwy

docs/guide/api-hmr.md

@@ -206,3 +206,9 @@ Send custom events back to Vite's dev server.
 If called before connected, the data will be buffered and sent once the connection is established.
 
 See [Client-server Communication](/guide/api-plugin.html#client-server-communication) for more details.
+
+## Further Reading
+
+If you'd like to learn more about how to use the HMR API and how it works under-the-hood. Check out these resources:
+
+- [Hot Module Replacement is Easy](https://bjornlu.com/blog/hot-module-replacement-is-easy)

docs/guide/api-plugin.md

@@ -402,6 +402,7 @@ Vite plugins can also provide hooks that serve Vite-specific purposes. These hoo
 ### `handleHotUpdate`
 
 - **Type:** `(ctx: HmrContext) => Array<ModuleNode> | void | Promise<Array<ModuleNode> | void>`
+- **See also:** [HMR API](./api-hmr)
 
   Perform custom HMR update handling. The hook receives a context object with the following signature:
 
@@ -423,10 +424,31 @@ Vite plugins can also provide hooks that serve Vite-specific purposes. These hoo
 
   - Filter and narrow down the affected module list so that the HMR is more accurate.
 
-  - Return an empty array and perform complete custom HMR handling by sending custom events to the client (example uses `server.hot` which was introduced in Vite 5.1, it is recommended to also use `server.ws` if you support lower versions):
+  - Return an empty array and perform a full reload:
+
+    ```js
+    handleHotUpdate({ server, modules, timestamp }) {
+      // Also use `server.ws.send` to support Vite <5.1 if needed
+      server.hot.send({ type: 'full-reload' })
+      // Invalidate modules manually
+      const invalidatedModules = new Set()
+      for (const mod of modules) {
+        server.moduleGraph.invalidateModule(
+          mod,
+          invalidatedModules,
+          timestamp,
+          true
+        )
+      }
+      return []
+    }
+    ```
+
+  - Return an empty array and perform complete custom HMR handling by sending custom events to the client:
 
     ```js
     handleHotUpdate({ server }) {
+      // Also use `server.ws.send` to support Vite <5.1 if needed
       server.hot.send({
         type: 'custom',
         event: 'special-update',