feat: add reactRefreshHost option to support module federation HMR

Author: protoEvangelion

packages/common/refresh-utils.ts

@@ -21,6 +21,7 @@ export function addRefreshWrapper<M extends { mappings: string }>(
   map: M | string | typeof avoidSourceMapOption,
   pluginName: string,
   id: string,
+  reactRefreshHost = '',
 ): { code: string; map: M | null | string } {
   const hasRefresh = refreshContentRE.test(code)
   const onlyReactComp = !hasRefresh && reactCompRE.test(code)
@@ -70,7 +71,8 @@ if (import.meta.hot && !inWebWorker) {
   }
 
   const sharedHead = removeLineBreaksIfNeeded(
-    `import * as RefreshRuntime from "${runtimePublicPath}";
+    `import * as RefreshRuntime from "${reactRefreshHost}${runtimePublicPath}";
+
 const inWebWorker = typeof WorkerGlobalScope !== 'undefined' && self instanceof WorkerGlobalScope;
 
 `,

packages/plugin-react-swc/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+### Add option `reactRefreshHost`
+
+Add option `reactRefreshHost` to set React refresh runtime url prefix.
+This is useful in module federation context to enable HMR by setting the host url on a Vite config which is serving a remote app.
+See full discussion here: https://github.com/module-federation/vite/issues/183#issuecomment-2751825367
+
+```ts
+export default defineConfig({
+  plugins: [react({ reactRefreshHost: 'http://localhost:3000' })],
+})
+```
+
 ## 3.9.0-beta.2 (2025-04-09)
 
 ## 3.9.0-beta.0 (2025-04-09)

packages/plugin-react-swc/README.md

@@ -93,6 +93,16 @@ react({
 })
 ```
 
+### reactRefreshHost
+
+The `reactRefreshHost` option is only necessary in a module federation context. It allows HMR to work between a remote & host server. In your remote vite config you would add your host origin:
+
+```js
+react({ reactRefreshHost: 'http://localhost:3000' })
+```
+
+Under the hood this simply updates the react refresh url from "/@react-refresh" to "http://localhost:3000/@react-refresh" to ensure you get only one Fast Refresh runtime in the whole application.
+
 ### useAtYourOwnRisk_mutateSwcOptions
 
 The future of Vite is with OXC, and from the beginning this was a design choice to not exposed too many specialties from SWC so that Vite React users can move to another transformer later.

packages/plugin-react-swc/src/index.ts

@@ -58,6 +58,14 @@ type Options = {
    * Exclusion of node_modules should be handled by the function if needed.
    */
   parserConfig?: (id: string) => ParserConfig | undefined
+  /**
+   * React refresh runtime url prefix.
+   * Useful in module federation context to enable HMR by
+   * setting the host url on a vite config which is serving a remote app.
+   * @example
+   * reactRefreshHost: 'http://localhost:3000'
+   */
+  reactRefreshHost?: string
   /**
    * The future of Vite is with OXC, and from the beginning this was a design choice
    * to not exposed too many specialties from SWC so that Vite React users can move to
@@ -78,6 +86,7 @@ const react = (_options?: Options): PluginOption[] => {
       : undefined,
     devTarget: _options?.devTarget ?? 'es2020',
     parserConfig: _options?.parserConfig,
+    reactRefreshHost: _options?.reactRefreshHost,
     useAtYourOwnRisk_mutateSwcOptions:
       _options?.useAtYourOwnRisk_mutateSwcOptions,
   }
@@ -152,6 +161,7 @@ const react = (_options?: Options): PluginOption[] => {
           result.map!,
           '@vitejs/plugin-react-swc',
           id,
+          options.reactRefreshHost,
         )
       },
     },

packages/plugin-react/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+### Add option `reactRefreshHost`
+
+Add option `reactRefreshHost` to set React refresh runtime url prefix.
+This is useful in module federation context to enable HMR by setting the host url on a Vite config which is serving a remote app.
+See full discussion here: https://github.com/module-federation/vite/issues/183#issuecomment-2751825367
+
+```ts
+export default defineConfig({
+  plugins: [react({ reactRefreshHost: 'http://localhost:3000' })],
+})
+```
+
 ## 4.4.0-beta.1 (2025-04-09)
 
 ## 4.4.0-beta.0 (2025-04-09)

packages/plugin-react/README.md

@@ -94,6 +94,16 @@ This option does not enable _code transformation_. That is handled by esbuild.
 
 Here's the [complete list of Babel parser plugins](https://babeljs.io/docs/en/babel-parser#ecmascript-proposalshttpsgithubcombabelproposals).
 
+### reactRefreshHost
+
+The `reactRefreshHost` option is only necessary in a module federation context. It allows HMR to work between a remote & host server. In your remote vite config you would add your host origin:
+
+```js
+react({ reactRefreshHost: 'http://localhost:3000' })
+```
+
+Under the hood this simply updates the react refresh url from "/@react-refresh" to "http://localhost:3000/@react-refresh" to ensure you get only one Fast Refresh runtime in the whole application.
+
 ## Middleware mode
 
 In [middleware mode](https://vite.dev/config/server-options.html#server-middlewaremode), you should make sure your entry `index.html` file is transformed by Vite. Here's an example for an Express server:

packages/plugin-react/src/index.ts

@@ -49,6 +49,14 @@ export interface Options {
   babel?:
     | BabelOptions
     | ((id: string, options: { ssr?: boolean }) => BabelOptions)
+  /**
+   * React refresh runtime url prefix.
+   * Useful in module federation context to enable HMR by
+   * setting the host url on a vite config which is serving a remote app.
+   * @example
+   * reactRefreshHost: 'http://localhost:3000'
+   */
+  reactRefreshHost?: string
 }
 
 export type BabelOptions = Omit<
@@ -263,6 +271,7 @@ export default function viteReact(opts: Options = {}): PluginOption[] {
           result.map!,
           '@vitejs/plugin-react',
           id,
+          opts.reactRefreshHost
         )
       }
     },