@module-federation/bridge-react 0.0.0-docs-remove-invalid-lark-link-20251205062649

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,150 @@
+/**
+ * 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>
+      );
+    };
+
+    const DefaultFallback = ({ error }: FallbackProps) => (
+      <div role="alert">
+        <p>Something went wrong:</p>
+        <pre style={{ color: 'red' }}>{error.message}</pre>
+      </div>
+    );
+
+    const BridgeWrapper = ({
+      basename,
+      moduleName,
+      memoryRoute,
+      propsInfo,
+      fallback,
+    }: {
+      basename?: string;
+      moduleName?: string;
+      memoryRoute?: any;
+      propsInfo: T;
+      fallback?: React.ComponentType<FallbackProps>;
+    }) => (
+      <ErrorBoundary FallbackComponent={fallback || DefaultFallback}>
+        <RawComponent
+          appInfo={{
+            moduleName,
+            basename,
+            memoryRoute,
+          }}
+          propsInfo={propsInfo}
+        />
+      </ErrorBoundary>
+    );
+
+    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 rootComponentWithErrorBoundary = (
+          <BridgeWrapper
+            basename={basename}
+            moduleName={moduleName}
+            memoryRoute={memoryRoute}
+            fallback={fallback as React.ComponentType<FallbackProps>}
+            propsInfo={
+              {
+                ...propsInfo,
+                basename,
+                ...(beforeBridgeRenderRes as any)?.extraProps,
+              } as T
+            }
+          />
+        );
+
+        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/RemoteAppWrapper.tsx

@@ -0,0 +1,108 @@
+/**
+ * Shared RemoteAppWrapper component used by both base and router versions
+ * This component handles the lifecycle of remote Module Federation apps
+ */
+import React, { useEffect, useRef, useState, forwardRef } from 'react';
+import { LoggerInstance, getRootDomDefaultClassName } from '../utils';
+import { federationRuntime } from '../provider/plugin';
+import { RemoteComponentProps, RemoteAppParams } from '../types';
+
+export 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>
+  );
+});

package/src/remote/base-component/component.tsx

@@ -0,0 +1,2 @@
+import { RemoteAppWrapper } from '../RemoteAppWrapper';
+export default RemoteAppWrapper;

package/src/remote/base-component/create.tsx

@@ -0,0 +1,23 @@
+import RemoteApp from './component';
+import {
+  createLazyRemoteComponentFactory,
+  createRemoteAppComponentFactory,
+  createDeprecatedRemoteComponentFactory,
+  type LazyRemoteComponentInfo,
+} from '../createHelpers';
+
+export type { LazyRemoteComponentInfo };
+
+const createLazyRemoteComponent = createLazyRemoteComponentFactory(RemoteApp);
+
+export const createRemoteAppComponent =
+  createRemoteAppComponentFactory(RemoteApp);
+
+/**
+ * @deprecated createRemoteComponent is deprecated, please use createRemoteAppComponent instead!
+ */
+export const createRemoteComponent = createDeprecatedRemoteComponentFactory(
+  createRemoteAppComponent,
+);
+
+export { createLazyRemoteComponent };

package/src/remote/base-component/index.tsx

@@ -0,0 +1,10 @@
+/**
+ * Base entry point without React Router dependencies
+ * Re-exports from base/create.tsx
+ */
+export {
+  createRemoteAppComponent,
+  createRemoteComponent,
+  createLazyRemoteComponent,
+  type LazyRemoteComponentInfo,
+} from './create';