refactor(bridge-react): modify the default mode of the bridge to legacy mode to reduce redundant code (#3711)

Author: danpeen

.changeset/wise-ways-occur.md

@@ -0,0 +1,6 @@
+---
+'@module-federation/bridge-react': patch
+'website-new': patch
+---
+
+refactor(bridge-react): modify the default mode of the bridge to legacy mode to reduce redundant code

apps/router-demo/router-remote1-2001/src/export-App.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
 import App from './App';
-import { createBridgeComponent } from '@module-federation/bridge-react/legacy';
+import { createBridgeComponent } from '@module-federation/bridge-react';
 
 const provider = createBridgeComponent({
   rootComponent: App,

apps/website-new/docs/en/practice/bridge/react-bridge.mdx

@@ -16,17 +16,14 @@
 
 You can choose specific import paths based on the React version used in your project:
 
-```jsx
-// Auto-detect React version (recommended for most scenarios)
+```tsx
+// Explicitly specify React 16/17 version (recommended for React 16/17)
 import { createBridgeComponent } from '@module-federation/bridge-react';
 
-// Explicitly specify React 16/17 version (Legacy mode)
-import { createBridgeComponent } from '@module-federation/bridge-react/legacy';
-
-// Explicitly specify React 18 version
+// Explicitly specify React 18 version (recommended for React 18)
 import { createBridgeComponent } from '@module-federation/bridge-react/v18';
 
-// Explicitly specify React 19 version
+// Explicitly specify React 19 version (recommended for React 19)
 import { createBridgeComponent } from '@module-federation/bridge-react/v19';
 ```
 

apps/website-new/docs/zh/practice/bridge/react-bridge.mdx

@@ -16,17 +16,14 @@
 
 您可以根据项目中使用的 React 版本，选择特定的导入方式：
 
-```jsx
-// 自动检测 React 版本（适用于 React 16/17/18）
+```tsx
+// Explicitly specify React 16/17 version (recommended for React 16/17)
 import { createBridgeComponent } from '@module-federation/bridge-react';
 
-// 明确指定 React 16/17 版本（Legacy 模式）
-import { createBridgeComponent } from '@module-federation/bridge-react/legacy';
-
-// 明确指定 React 18 版本
+// Explicitly specify React 18 version (recommended for React 18)
 import { createBridgeComponent } from '@module-federation/bridge-react/v18';
 
-// 明确指定 React 19 版本
+// Explicitly specify React 19 version (recommended for React 19)
 import { createBridgeComponent } from '@module-federation/bridge-react/v19';
 ```
 

packages/bridge/bridge-react/package.json

@@ -21,11 +21,6 @@
       "import": "./dist/index.es.js",
       "require": "./dist/index.cjs.js"
     },
-    "./legacy": {
-      "types": "./dist/legacy.d.ts",
-      "import": "./dist/legacy.es.js",
-      "require": "./dist/legacy.cjs.js"
-    },
     "./v18": {
       "types": "./dist/v18.d.ts",
       "import": "./dist/v18.es.js",

packages/bridge/bridge-react/src/index.ts

@@ -1,8 +1,14 @@
+/**
+ * Entry point for React 16/17 (legacy) specific bridge components
+ * This file provides support for React 16 and 17 versions, using the traditional ReactDOM.render API
+ */
+export { createBridgeComponent } from './provider/versions/legacy';
 export { createRemoteComponent } from './remote/create';
-export { createBridgeComponent } from './provider/create';
+export type { CreateRootOptions, Root } from './provider/versions/legacy';
 export type {
   ProviderParams,
-  RenderFnParams,
+  ProviderFnParams,
+  RootType,
   DestroyParams,
   RenderParams,
 } from './types';

packages/bridge/bridge-react/src/legacy.ts

@@ -16,11 +16,55 @@ export interface Root {
   unmount(): void;
 }
 
+/**
+ * Default createRoot function that automatically detects React version and uses the appropriate API(only support React 16/17, 18)
+ *
+ * Note: Users can also directly import version-specific bridge components:
+ * - import { createBridgeComponent } from '@module-federation/bridge-react'
+ * - import { createBridgeComponent } from '@module-federation/bridge-react/v18'
+ * - import { createBridgeComponent } from '@module-federation/bridge-react/v19'
+ */
+
 export function createReact16Or17Root(
   container: Element | DocumentFragment,
 ): Root {
   return {
     render(children: React.ReactNode) {
+      /**
+       * Detect React version
+       */
+      const reactVersion = ReactDOM.version || '';
+      const isReact18 = reactVersion.startsWith('18');
+      const isReact19 = reactVersion.startsWith('19');
+
+      /**
+       * Throw error for React 19
+       *
+       * Note: Due to Module Federation sharing mechanism, the actual version detected here
+       * might be 18 or 19, even if the application itself uses React 16/17.
+       * This happens because in MF environments, different remote modules may share different React versions.
+       * The console may throw warnings about version and API mismatches. If you need to resolve these issues,
+       * consider disabling the shared configuration for React.
+       */
+      if (isReact19) {
+        throw new Error(
+          `React 19 detected in legacy mode. This is not supported. ` +
+            `Please use the version-specific import: ` +
+            `import { createBridgeComponent } from '@module-federation/bridge-react/v19'`,
+        );
+      }
+
+      /**
+       * Provide warning for React 18
+       */
+      if (isReact18) {
+        console.warn(
+          `[Bridge-React] React 18 detected in legacy mode. ` +
+            `For better compatibility, please use the version-specific import: ` +
+            `import { createBridgeComponent } from '@module-federation/bridge-react/v18'`,
+        );
+      }
+
       // @ts-ignore - React 17's render method is deprecated but still functional
       ReactDOM.render(children, container);
     },
@@ -34,8 +78,8 @@ export function createBridgeComponent<T = any>(
   bridgeInfo: Omit<ProviderFnParams<T>, 'createRoot'>,
 ) {
   const fullBridgeInfo = {
-    ...bridgeInfo,
     createRoot: createReact16Or17Root,
+    ...bridgeInfo,
   } as unknown as ProviderFnParams<T>;
 
   return createBaseBridgeComponent(fullBridgeInfo);

packages/bridge/bridge-react/src/provider/create.tsx

@@ -39,8 +39,8 @@ export function createBridgeComponent<T = any>(
   bridgeInfo: Omit<ProviderFnParams<T>, 'createRoot'>,
 ) {
   const fullBridgeInfo = {
-    ...bridgeInfo,
     createRoot: createReact18Root,
+    ...bridgeInfo,
   } as unknown as ProviderFnParams<T>;
 
   return createBaseBridgeComponent(fullBridgeInfo);

packages/bridge/bridge-react/src/provider/versions/legacy.ts

@@ -40,8 +40,8 @@ export function createBridgeComponent<T = any>(
   bridgeInfo: Omit<ProviderFnParams<T>, 'createRoot'>,
 ) {
   const fullBridgeInfo = {
-    ...bridgeInfo,
     createRoot: createReact19Root,
+    ...bridgeInfo,
   } as unknown as ProviderFnParams<T>;
 
   return createBaseBridgeComponent(fullBridgeInfo);

packages/bridge/bridge-react/src/provider/versions/v18.ts

@@ -24,8 +24,6 @@ export default defineConfig({
         router: path.resolve(__dirname, 'src/router/default.tsx'),
         'router-v5': path.resolve(__dirname, 'src/router/v5.tsx'),
         'router-v6': path.resolve(__dirname, 'src/router/v6.tsx'),
-        v16: path.resolve(__dirname, 'src/legacy.ts'),
-        legacy: path.resolve(__dirname, 'src/legacy.ts'),
         v18: path.resolve(__dirname, 'src/v18.ts'),
         v19: path.resolve(__dirname, 'src/v19.ts'),
       },