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

.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 change.
+   *
+   * @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 change.
+   *
+   * @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: {