@module-federation/bridge-react 0.0.0-feat-support-bridge-react-router-v7-20251015102312

package/src/lazy/wrapNoSSR.tsx

@@ -0,0 +1,10 @@
+import { createLazyComponent } from './createLazyComponent';
+import type { CreateLazyComponentOptions } from './createLazyComponent';
+
+export function wrapNoSSR<T, E extends keyof T>(
+  createLazyComponentFn: typeof createLazyComponent<T, E>,
+) {
+  return (options: Omit<CreateLazyComponentOptions<T, E>, 'noSSR'>) => {
+    return createLazyComponentFn({ ...options, noSSR: true });
+  };
+}

package/src/modern-app-env.d.ts

@@ -0,0 +1,2 @@
+/// <reference types='@modern-js/module-tools/types' />
+/// <reference types='@modern-js/plugin-testing/types' />

package/src/plugins/lazy-load-component-plugin.spec.ts

@@ -0,0 +1,21 @@
+import { describe, it, expect, vi } from 'vitest';
+import { lazyLoadComponentPlugin } from './lazy-load-component-plugin';
+import type { ModuleFederation } from '@module-federation/runtime';
+
+describe('lazyLoadComponentPlugin', () => {
+  it('should register lazy load component methods on the instance', () => {
+    const instance = {
+      registerPlugins: vi.fn(),
+    } as unknown as ModuleFederation;
+
+    const plugin = lazyLoadComponentPlugin();
+    if (plugin.apply) {
+      plugin.apply(instance);
+    }
+
+    expect(instance.registerPlugins).toHaveBeenCalled();
+    expect(typeof instance.createLazyComponent).toBe('function');
+    expect(typeof instance.prefetch).toBe('function');
+    expect(typeof instance.collectSSRAssets).toBe('function');
+  });
+});

package/src/plugins/lazy-load-component-plugin.ts

@@ -0,0 +1,57 @@
+import type {
+  ModuleFederation,
+  ModuleFederationRuntimePlugin,
+} from '@module-federation/runtime';
+import {
+  createLazyComponent,
+  prefetch,
+  collectSSRAssets,
+  autoFetchDataPlugin,
+} from '../lazy';
+import type { CreateLazyComponentOptions, PrefetchOptions } from '../lazy';
+
+declare module '@module-federation/runtime-core' {
+  interface ModuleFederation {
+    createLazyComponent<T, E extends keyof T>(
+      options: Omit<CreateLazyComponentOptions<T, E>, 'instance'>,
+    ): ReturnType<typeof createLazyComponent<T, E>>;
+    prefetch(
+      options: Omit<PrefetchOptions, 'instance'>,
+    ): ReturnType<typeof prefetch>;
+    collectSSRAssets(
+      options: Omit<Parameters<typeof collectSSRAssets>[0], 'instance'>,
+    ): ReturnType<typeof collectSSRAssets>;
+  }
+}
+
+export function lazyLoadComponentPlugin(): ModuleFederationRuntimePlugin {
+  return {
+    name: 'lazy-load-component-plugin',
+    apply(instance: ModuleFederation) {
+      instance.registerPlugins([autoFetchDataPlugin()]);
+
+      instance.createLazyComponent = (options) => {
+        return createLazyComponent({
+          instance,
+          ...options,
+        });
+      };
+
+      instance.prefetch = (options) => {
+        return prefetch({
+          instance,
+          ...options,
+        });
+      };
+
+      instance.collectSSRAssets = (options) => {
+        return collectSSRAssets({
+          instance,
+          ...options,
+        });
+      };
+    },
+  };
+}
+
+export default lazyLoadComponentPlugin;

package/src/provider/context.tsx

@@ -0,0 +1,4 @@
+import React from 'react';
+import { ProviderParams } from '../types';
+
+export const RouterContext = React.createContext<ProviderParams | null>(null);

package/src/provider/plugin.ts

@@ -0,0 +1,22 @@
+import type {
+  ModuleFederationRuntimePlugin,
+  ModuleFederation,
+} from '@module-federation/runtime';
+
+export type FederationRuntimeType = {
+  instance: ModuleFederation | null;
+};
+
+export const federationRuntime: FederationRuntimeType = { instance: null };
+
+function BridgeReactPlugin(): ModuleFederationRuntimePlugin {
+  return {
+    name: 'bridge-react-plugin',
+    beforeInit(args) {
+      federationRuntime.instance = args.origin;
+      return args;
+    },
+  };
+}
+
+export default BridgeReactPlugin;

package/src/provider/versions/bridge-base.tsx

@@ -0,0 +1,127 @@
+/**
+ * Base bridge component implementation
+ * This file contains bridge component logic shared across all React versions
+ */
+import * as React from 'react';
+import type {
+  ProviderParams,
+  ProviderFnParams,
+  RootType,
+  DestroyParams,
+  RenderParams,
+  CreateRootOptions,
+} from '../../types';
+import { ErrorBoundary, FallbackProps } from 'react-error-boundary';
+import { RouterContext } from '../context';
+import { LoggerInstance } from '../../utils';
+import { federationRuntime } from '../plugin';
+
+export function createBaseBridgeComponent<T>({
+  createRoot,
+  defaultRootOptions,
+  ...bridgeInfo
+}: ProviderFnParams<T>) {
+  return () => {
+    const rootMap = new Map<any, RootType>();
+    const instance = federationRuntime.instance;
+    LoggerInstance.debug(
+      `createBridgeComponent instance from props >>>`,
+      instance,
+    );
+
+    const RawComponent = (info: { propsInfo: T; appInfo: ProviderParams }) => {
+      const { appInfo, propsInfo, ...restProps } = info;
+      const { moduleName, memoryRoute, basename = '/' } = appInfo;
+      return (
+        <RouterContext.Provider value={{ moduleName, basename, memoryRoute }}>
+          <bridgeInfo.rootComponent
+            {...propsInfo}
+            basename={basename}
+            {...restProps}
+          />
+        </RouterContext.Provider>
+      );
+    };
+
+    return {
+      async render(info: RenderParams) {
+        LoggerInstance.debug(`createBridgeComponent render Info`, info);
+        const {
+          moduleName,
+          dom,
+          basename,
+          memoryRoute,
+          fallback,
+          rootOptions,
+          ...propsInfo
+        } = info;
+
+        const mergedRootOptions: CreateRootOptions | undefined = {
+          ...defaultRootOptions,
+          ...(rootOptions as CreateRootOptions),
+        };
+
+        const beforeBridgeRenderRes =
+          instance?.bridgeHook?.lifecycle?.beforeBridgeRender?.emit(info) || {};
+
+        const BridgeWrapper = ({ basename }: { basename?: string }) => (
+          <ErrorBoundary
+            FallbackComponent={fallback as React.ComponentType<FallbackProps>}
+          >
+            <RawComponent
+              appInfo={{
+                moduleName,
+                basename,
+                memoryRoute,
+              }}
+              propsInfo={
+                {
+                  ...propsInfo,
+                  basename,
+                  ...(beforeBridgeRenderRes as any)?.extraProps,
+                } as T
+              }
+            />
+          </ErrorBoundary>
+        );
+
+        const rootComponentWithErrorBoundary = (
+          <BridgeWrapper basename={basename} />
+        );
+
+        if (bridgeInfo.render) {
+          await Promise.resolve(
+            bridgeInfo.render(rootComponentWithErrorBoundary, dom),
+          ).then((root: RootType) => rootMap.set(dom, root));
+        } else {
+          let root = rootMap.get(dom);
+          // Do not call createRoot multiple times
+          if (!root && createRoot) {
+            root = createRoot(dom, mergedRootOptions);
+            rootMap.set(dom, root as any);
+          }
+
+          if (root && 'render' in root) {
+            root.render(rootComponentWithErrorBoundary);
+          }
+        }
+        instance?.bridgeHook?.lifecycle?.afterBridgeRender?.emit(info) || {};
+      },
+
+      destroy(info: DestroyParams) {
+        const { dom } = info;
+        LoggerInstance.debug(`createBridgeComponent destroy Info`, info);
+        const root = rootMap.get(dom);
+        if (root) {
+          if ('unmount' in root) {
+            root.unmount();
+          } else {
+            LoggerInstance.warn('Root does not have unmount method');
+          }
+          rootMap.delete(dom);
+        }
+        instance?.bridgeHook?.lifecycle?.afterBridgeDestroy?.emit(info);
+      },
+    };
+  };
+}

package/src/provider/versions/legacy.ts

@@ -0,0 +1,87 @@
+/**
+ * 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
+ */
+import type { ProviderFnParams } from '../../types';
+import { createBaseBridgeComponent } from './bridge-base';
+import ReactDOM from 'react-dom';
+import { LoggerInstance } from '../../utils';
+
+export interface CreateRootOptions {
+  identifierPrefix?: string;
+  onRecoverableError?: (error: unknown, errorInfo: unknown) => void;
+}
+
+export interface Root {
+  render(children: React.ReactNode): void;
+  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) {
+        LoggerInstance.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);
+    },
+    unmount() {
+      ReactDOM.unmountComponentAtNode(container as Element);
+    },
+  };
+}
+
+export function createBridgeComponent<T = any>(
+  bridgeInfo: Omit<ProviderFnParams<T>, 'createRoot'>,
+) {
+  const fullBridgeInfo = {
+    createRoot: createReact16Or17Root,
+    ...bridgeInfo,
+  } as unknown as ProviderFnParams<T>;
+
+  return createBaseBridgeComponent(fullBridgeInfo);
+}

package/src/provider/versions/v18.ts

@@ -0,0 +1,47 @@
+/**
+ * Entry point for React 18 specific bridge components
+ */
+import React from 'react';
+import { createRoot as createReactRoot, hydrateRoot } from 'react-dom/client';
+import { createBaseBridgeComponent } from './bridge-base';
+import type { ProviderFnParams } from '../../types';
+
+export interface CreateRootOptions {
+  identifierPrefix?: string;
+  onRecoverableError?: (error: unknown, errorInfo: unknown) => void;
+}
+
+export interface Root {
+  render(children: React.ReactNode): void;
+  unmount(): void;
+}
+
+export function createReact18Root(
+  container: Element | DocumentFragment,
+  options?: CreateRootOptions,
+): Root {
+  return createReactRoot(container, options);
+}
+
+export function hydrateReact18Root(
+  container: Element | DocumentFragment,
+  initialChildren: React.ReactNode,
+  options?: CreateRootOptions,
+) {
+  return hydrateRoot(
+    container as Element,
+    initialChildren as React.ReactElement,
+    options,
+  );
+}
+
+export function createBridgeComponent<T = any>(
+  bridgeInfo: Omit<ProviderFnParams<T>, 'createRoot'>,
+) {
+  const fullBridgeInfo = {
+    createRoot: createReact18Root,
+    ...bridgeInfo,
+  } as unknown as ProviderFnParams<T>;
+
+  return createBaseBridgeComponent(fullBridgeInfo);
+}

package/src/provider/versions/v19.ts

@@ -0,0 +1,48 @@
+/**
+ * Entry point for React 19 specific bridge components
+ * This file provides support for React 19 version, using the new ReactDOM.createRoot API
+ */
+import React from 'react';
+import { createRoot, hydrateRoot } from 'react-dom/client';
+import { createBaseBridgeComponent } from './bridge-base';
+import type { ProviderFnParams } from '../../types';
+export interface CreateRootOptions {
+  identifierPrefix?: string;
+  onRecoverableError?: (error: unknown, errorInfo: unknown) => void;
+  transitionCallbacks?: unknown;
+}
+
+export interface Root {
+  render(children: React.ReactNode): void;
+  unmount(): void;
+}
+
+export function createReact19Root(
+  container: Element | DocumentFragment,
+  options?: CreateRootOptions,
+): Root {
+  return createRoot(container as Element, options);
+}
+
+export function hydrateReact19Root(
+  container: Element | DocumentFragment,
+  initialChildren: React.ReactNode,
+  options?: CreateRootOptions,
+): Root {
+  return hydrateRoot(
+    container as Element,
+    initialChildren as React.ReactElement,
+    options,
+  );
+}
+
+export function createBridgeComponent<T = any>(
+  bridgeInfo: Omit<ProviderFnParams<T>, 'createRoot'>,
+) {
+  const fullBridgeInfo = {
+    createRoot: createReact19Root,
+    ...bridgeInfo,
+  } as unknown as ProviderFnParams<T>;
+
+  return createBaseBridgeComponent(fullBridgeInfo);
+}

package/src/remote/component.tsx

@@ -0,0 +1,211 @@
+import React, {
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+  forwardRef,
+} from 'react';
+import * as ReactRouterDOM from 'react-router-dom';
+import { dispatchPopstateEnv } from '@module-federation/bridge-shared';
+import { LoggerInstance, pathJoin, getRootDomDefaultClassName } from '../utils';
+import { federationRuntime } from '../provider/plugin';
+import { RemoteComponentProps, RemoteAppParams } from '../types';
+
+const RemoteAppWrapper = forwardRef(function (
+  props: RemoteAppParams & RemoteComponentProps,
+  ref,
+) {
+  const {
+    moduleName,
+    memoryRoute,
+    basename,
+    providerInfo,
+    className,
+    style,
+    fallback,
+    loading,
+    ...resProps
+  } = props;
+
+  const instance = federationRuntime.instance;
+  const rootRef: React.MutableRefObject<HTMLDivElement | null> =
+    ref && 'current' in ref
+      ? (ref as React.MutableRefObject<HTMLDivElement | null>)
+      : useRef(null);
+
+  const renderDom: React.MutableRefObject<HTMLElement | null> = useRef(null);
+  const providerInfoRef = useRef<any>(null);
+  const [initialized, setInitialized] = useState(false);
+
+  LoggerInstance.debug(`RemoteAppWrapper instance from props >>>`, instance);
+
+  // 初始化远程组件
+  useEffect(() => {
+    if (initialized) return;
+    const providerReturn = providerInfo();
+    providerInfoRef.current = providerReturn;
+    setInitialized(true);
+
+    return () => {
+      if (providerInfoRef.current?.destroy) {
+        LoggerInstance.debug(
+          `createRemoteAppComponent LazyComponent destroy >>>`,
+          { moduleName, basename, dom: renderDom.current },
+        );
+
+        instance?.bridgeHook?.lifecycle?.beforeBridgeDestroy?.emit({
+          moduleName,
+          dom: renderDom.current,
+          basename,
+          memoryRoute,
+          fallback,
+          ...resProps,
+        });
+
+        providerInfoRef.current?.destroy({
+          moduleName,
+          dom: renderDom.current,
+        });
+
+        instance?.bridgeHook?.lifecycle?.afterBridgeDestroy?.emit({
+          moduleName,
+          dom: renderDom.current,
+          basename,
+          memoryRoute,
+          fallback,
+          ...resProps,
+        });
+      }
+    };
+  }, [moduleName]);
+
+  // trigger render after props updated
+  useEffect(() => {
+    if (!initialized || !providerInfoRef.current) return;
+
+    let renderProps = {
+      moduleName,
+      dom: rootRef.current,
+      basename,
+      memoryRoute,
+      fallback,
+      ...resProps,
+    };
+    renderDom.current = rootRef.current;
+
+    const beforeBridgeRenderRes =
+      instance?.bridgeHook?.lifecycle?.beforeBridgeRender?.emit(renderProps) ||
+      {};
+    // @ts-ignore
+    renderProps = { ...renderProps, ...beforeBridgeRenderRes.extraProps };
+    providerInfoRef.current.render(renderProps);
+    instance?.bridgeHook?.lifecycle?.afterBridgeRender?.emit(renderProps);
+  }, [initialized, ...Object.values(props)]);
+
+  // bridge-remote-root
+  const rootComponentClassName = `${getRootDomDefaultClassName(moduleName)} ${className || ''}`;
+  return (
+    <div className={rootComponentClassName} style={style} ref={rootRef}>
+      {loading}
+    </div>
+  );
+});
+
+interface ExtraDataProps {
+  basename?: string;
+}
+
+export function withRouterData<
+  P extends Parameters<typeof RemoteAppWrapper>[0],
+>(
+  WrappedComponent: React.ComponentType<P & ExtraDataProps>,
+): React.FC<Omit<P, keyof ExtraDataProps>> {
+  const Component = forwardRef(function (props: any, ref) {
+    if (props?.basename) {
+      return (
+        <WrappedComponent {...props} basename={props.basename} ref={ref} />
+      );
+    }
+    let enableDispathPopstate = false;
+    let routerContextVal: any;
+    try {
+      ReactRouterDOM.useLocation();
+      enableDispathPopstate = true;
+    } catch {
+      enableDispathPopstate = false;
+    }
+    let basename = '/';
+
+    if (!props.basename && enableDispathPopstate) {
+      const ReactRouterDOMAny: any = ReactRouterDOM;
+      // Avoid building tools checking references
+      const useRouteMatch = ReactRouterDOMAny['use' + 'RouteMatch']; //v5
+      const useHistory = ReactRouterDOMAny['use' + 'History']; //v5
+      const useHref = ReactRouterDOMAny['use' + 'Href'];
+      const UNSAFE_RouteContext = ReactRouterDOMAny['UNSAFE_' + 'RouteContext'];
+
+      if (UNSAFE_RouteContext /* react-router@6 */) {
+        if (useHref) {
+          basename = useHref?.('/');
+        }
+        routerContextVal = useContext(UNSAFE_RouteContext);
+        if (
+          routerContextVal &&
+          routerContextVal.matches &&
+          routerContextVal.matches.length > 0
+        ) {
+          const matchIndex = routerContextVal.matches.length - 1;
+          const pathnameBase =
+            routerContextVal.matches[matchIndex].pathnameBase;
+          basename = pathJoin(basename, pathnameBase || '/');
+        }
+      } /* react-router@5 */ else {
+        const match = useRouteMatch?.(); // v5
+        if (useHistory /* react-router@5 */) {
+          // there is no dynamic switching of the router version in the project
+          // so hooks can be used in conditional judgment
+          const history = useHistory?.();
+          // To be compatible to history@4.10.1 and @5.3.0 we cannot write like this `history.createHref(pathname)`
+          basename = history?.createHref?.({ pathname: '/' });
+        }
+        if (match /* react-router@5 */) {
+          basename = pathJoin(basename, match?.path || '/');
+        }
+      }
+    }
+
+    LoggerInstance.debug(`createRemoteAppComponent withRouterData >>>`, {
+      ...props,
+      basename,
+      routerContextVal,
+      enableDispathPopstate,
+    });
+
+    if (enableDispathPopstate) {
+      const location = ReactRouterDOM.useLocation();
+      const [pathname, setPathname] = useState(location.pathname);
+
+      useEffect(() => {
+        if (pathname !== '' && pathname !== location.pathname) {
+          LoggerInstance.debug(
+            `createRemoteAppComponent dispatchPopstateEnv >>>`,
+            {
+              name: props.name,
+              pathname: location.pathname,
+            },
+          );
+          dispatchPopstateEnv();
+        }
+        setPathname(location.pathname);
+      }, [location]);
+    }
+
+    return <WrappedComponent {...(props as P)} basename={basename} ref={ref} />;
+  });
+
+  return forwardRef(function (props, ref) {
+    return <Component {...props} ref={ref} />;
+  }) as any;
+}
+
+export default withRouterData(RemoteAppWrapper);