feat(rspeedy/core): add dev.hmr and dev.liveReload (#458)

<!--
  Thank you for submitting a pull request!

We appreciate the time and effort you have invested in making these
changes. Please ensure that you provide enough information to allow
others to review your pull request.

Upon submission, your pull request will be automatically assigned with
reviewers.

If you want to learn more about contributing to this project, please
visit:
https://github.com/lynx-family/lynx-stack/blob/main/CONTRIBUTING.md.
-->

## Summary

<!-- Can you explain the reasoning behind implementing this change? What
problem or issue does this pull request resolve? -->

fix: #298

<!-- It would be helpful if you could provide any relevant context, such
as GitHub issues or related discussions. -->

## Checklist

<!--- Check and mark with an "x" -->

- [x] Tests updated (or not required).
- [x] Documentation updated (or not required).

---------

Signed-off-by: Qingyu Wang <[email protected]>
Co-authored-by: Yradex <[email protected]>

Author: colinaaa

.changeset/sweet-crabs-travel.md

@@ -0,0 +1,5 @@
+---
+"@lynx-js/rspeedy": patch
+---
+
+Support `dev.hmr` and `dev.liveReload`.

packages/rspeedy/core/etc/rspeedy.api.md

@@ -134,6 +134,8 @@ export function defineConfig(config: Config): Config;
 export interface Dev {
     assetPrefix?: string | boolean | undefined;
     client?: DevClient | undefined;
+    hmr?: boolean | undefined;
+    liveReload?: boolean | undefined;
     progressBar?: boolean | {
         id?: string;
     } | undefined;

packages/rspeedy/core/src/config/dev/index.ts

@@ -75,6 +75,88 @@ export interface Dev {
    */
   client?: Client | undefined
 
+  /**
+   * Whether to enable Hot Module Replacement (HMR).
+   *
+   * @remarks
+   *
+   * Defaults to `true`.
+   *
+   * By default, Rspeedy uses HMR as the preferred method to update modules. If HMR is disabled or cannot be used in certain scenarios, it will automatically fallback to {@link Dev.liveReload}.
+   *
+   * To completely disable both HMR and live reload, set both `dev.hmr` and `dev.liveReload` to `false`. Then, no WebSocket requests will be made to the dev server on the page, and the page will not automatically refresh when file changes.
+   *
+   * @example
+   *
+   * Disable HMR:
+   *
+   * ```js
+   * import { defineConfig } from '@lynx-js/rspeedy'
+   *
+   * export default defineConfig({
+   *   dev: {
+   *     hmr: false,
+   *   },
+   * })
+   * ```
+   *
+   * @example
+   *
+   * Disable both HMR and live reload:
+   *
+   * ```js
+   * import { defineConfig } from '@lynx-js/rspeedy'
+   *
+   * export default defineConfig({
+   *   dev: {
+   *     hmr: false,
+   *     liveReload: false,
+   *   },
+   * })
+   * ```
+   */
+  hmr?: boolean | undefined
+
+  /**
+   * Whether to enable live reload functionality.
+   *
+   * Defaults to `true`.
+   *
+   * Live reload is used as a fallback when {@link Dev.hmr} is disabled or cannot be used in certain scenarios. When enabled, the page will automatically refresh when source files are changed.
+   *
+   * To completely disable both HMR and live reload, set both `dev.hmr` and `dev.liveReload` to `false`. Then, no WebSocket requests will be made to the dev server on the page, and the page will not automatically refresh when file changes.
+   *
+   * @example
+   *
+   * Disable live reload:
+   *
+   * ```js
+   * import { defineConfig } from '@lynx-js/rspeedy'
+   *
+   * export default defineConfig({
+   *   dev: {
+   *     liveReload: false,
+   *   },
+   * })
+   * ```
+   *
+   * @example
+   *
+   * Disable both HMR and live reload:
+   *
+   * ```js
+   * import { defineConfig } from '@lynx-js/rspeedy'
+   *
+   * export default defineConfig({
+   *   dev: {
+   *     hmr: false,
+   *     liveReload: false,
+   *   },
+   * })
+   * ```
+   */
+  liveReload?: boolean | undefined
+
   /**
    * Watch specified files and directories for changes. When a file change is detected, it can trigger a page reload or restart the dev server.
    *

packages/rspeedy/core/src/plugins/dev.plugin.ts

@@ -116,7 +116,7 @@ export function pluginDev(
                   hostname
                 }&port=${
                   api.context.devServer?.port
-                }&pathname=/rsbuild-hmr&hot=true&live-reload=true&protocol=ws`
+                }&pathname=/rsbuild-hmr&hot=${options?.hmr ?? true}&live-reload=${options?.liveReload ?? true}&protocol=ws`
               )
               .set(
                 '@rspack/core/hot/dev-server',

packages/rspeedy/core/test/config/dev.test-d.ts

@@ -34,6 +34,16 @@ describe('Config - Dev', () => {
     })
   })
 
+  test('hmr', () => {
+    assertType<Dev>({ hmr: true })
+    assertType<Dev>({ hmr: false })
+  })
+
+  test('liveReload', () => {
+    assertType<Dev>({ liveReload: true })
+    assertType<Dev>({ liveReload: false })
+  })
+
   test('watchFiles', () => {
     assertType<Dev>({ watchFiles: { paths: '' } })
     assertType<Dev>({ watchFiles: { paths: [] } })

packages/rspeedy/core/test/plugins/dev.plugin.test.ts

@@ -356,6 +356,88 @@ describe('Plugins - Dev', () => {
     expect(config.output?.publicPath).not.toBe(`http://example.com:${port}`)
   })
 
+  test('dev.hmr default', async () => {
+    const rsbuild = await createStubRspeedy({})
+
+    const config = await rsbuild.unwrapConfig()
+
+    expect(config.resolve?.alias).toHaveProperty(
+      '@lynx-js/webpack-dev-transport/client',
+      expect.stringContaining('hot=true'),
+    )
+  })
+
+  test('dev.hmr: false', async () => {
+    const rsbuild = await createStubRspeedy({
+      dev: {
+        hmr: false,
+      },
+    })
+
+    const config = await rsbuild.unwrapConfig()
+
+    expect(config.resolve?.alias).toHaveProperty(
+      '@lynx-js/webpack-dev-transport/client',
+      expect.stringContaining('hot=false'),
+    )
+  })
+
+  test('dev.hmr: true', async () => {
+    const rsbuild = await createStubRspeedy({
+      dev: {
+        hmr: true,
+      },
+    })
+
+    const config = await rsbuild.unwrapConfig()
+
+    expect(config.resolve?.alias).toHaveProperty(
+      '@lynx-js/webpack-dev-transport/client',
+      expect.stringContaining('hot=true'),
+    )
+  })
+
+  test('dev.liveReload default', async () => {
+    const rsbuild = await createStubRspeedy({})
+
+    const config = await rsbuild.unwrapConfig()
+
+    expect(config.resolve?.alias).toHaveProperty(
+      '@lynx-js/webpack-dev-transport/client',
+      expect.stringContaining('live-reload=true'),
+    )
+  })
+
+  test('dev.liveReload: false', async () => {
+    const rsbuild = await createStubRspeedy({
+      dev: {
+        liveReload: false,
+      },
+    })
+
+    const config = await rsbuild.unwrapConfig()
+
+    expect(config.resolve?.alias).toHaveProperty(
+      '@lynx-js/webpack-dev-transport/client',
+      expect.stringContaining('live-reload=false'),
+    )
+  })
+
+  test('dev.liveReload: true', async () => {
+    const rsbuild = await createStubRspeedy({
+      dev: {
+        liveReload: true,
+      },
+    })
+
+    const config = await rsbuild.unwrapConfig()
+
+    expect(config.resolve?.alias).toHaveProperty(
+      '@lynx-js/webpack-dev-transport/client',
+      expect.stringContaining('live-reload=true'),
+    )
+  })
+
   test('websocketTransport', async () => {
     const rsbuild = await createStubRspeedy({
       dev: {