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

package/src/remote/createHelpers.tsx

@@ -0,0 +1,130 @@
+import React, { forwardRef } from 'react';
+import { ErrorBoundary, FallbackProps } from 'react-error-boundary';
+import { LoggerInstance } from '../utils';
+import {
+  RemoteComponentParams,
+  RemoteComponentProps,
+  RemoteModule,
+} from '../types';
+
+export type LazyRemoteComponentInfo<
+  T,
+  _E extends keyof T,
+> = RemoteComponentParams<T>;
+
+/**
+ * Creates a factory function for creating lazy remote components
+ * @param RemoteApp The RemoteAppWrapper component to use (with or without router)
+ */
+export function createLazyRemoteComponentFactory(
+  RemoteApp: React.ComponentType<any>,
+) {
+  return function createLazyRemoteComponent<
+    T = Record<string, unknown>,
+    E extends keyof T = keyof T,
+  >(info: LazyRemoteComponentInfo<T, E>) {
+    const exportName = info?.export || 'default';
+    return React.lazy(async () => {
+      LoggerInstance.debug(
+        `createRemoteAppComponent LazyComponent create >>>`,
+        {
+          lazyComponent: info.loader,
+          exportName,
+        },
+      );
+
+      try {
+        const m = (await info.loader()) as RemoteModule;
+        // @ts-ignore
+        const moduleName = m && m[Symbol.for('mf_module_id')];
+        LoggerInstance.debug(
+          `createRemoteAppComponent LazyComponent loadRemote info >>>`,
+          { name: moduleName, module: m, exportName },
+        );
+
+        // @ts-ignore
+        const exportFn = m[exportName];
+        if (exportName in m && typeof exportFn === 'function') {
+          const RemoteAppComponent = forwardRef<
+            HTMLDivElement,
+            RemoteComponentProps
+          >((props, ref) => {
+            return (
+              <RemoteApp
+                // change `name` key to `moduleName` to avoid same property `name` passed by user's props which may cause unexpected issues.
+                moduleName={moduleName}
+                providerInfo={exportFn}
+                exportName={info.export || 'default'}
+                fallback={info.fallback}
+                loading={info.loading}
+                ref={ref}
+                {...props}
+              />
+            );
+          });
+
+          return {
+            default: RemoteAppComponent,
+          };
+        } else {
+          LoggerInstance.debug(
+            `createRemoteAppComponent LazyComponent module not found >>>`,
+            { name: moduleName, module: m, exportName },
+          );
+          throw Error(
+            `Make sure that ${moduleName} has the correct export when export is ${String(
+              exportName,
+            )}`,
+          );
+        }
+      } catch (error) {
+        throw error;
+      }
+    });
+  };
+}
+
+/**
+ * Creates a factory function for creating remote app components
+ * @param RemoteApp The RemoteAppWrapper component to use (with or without router)
+ */
+export function createRemoteAppComponentFactory(
+  RemoteApp: React.ComponentType<any>,
+) {
+  const createLazyRemoteComponent = createLazyRemoteComponentFactory(RemoteApp);
+
+  return function createRemoteAppComponent<
+    T = Record<string, unknown>,
+    E extends keyof T = keyof T,
+  >(info: LazyRemoteComponentInfo<T, E>) {
+    const LazyComponent = createLazyRemoteComponent(info);
+    return forwardRef<HTMLDivElement, RemoteComponentProps>((props, ref) => {
+      return (
+        <ErrorBoundary
+          FallbackComponent={
+            info.fallback as React.ComponentType<FallbackProps>
+          }
+        >
+          <React.Suspense fallback={info.loading}>
+            <LazyComponent {...props} ref={ref} />
+          </React.Suspense>
+        </ErrorBoundary>
+      );
+    });
+  };
+}
+
+/**
+ * Creates the deprecated createRemoteComponent function
+ */
+export function createDeprecatedRemoteComponentFactory<
+  T = Record<string, unknown>,
+  E extends keyof T = keyof T,
+>(createFn: (info: LazyRemoteComponentInfo<T, E>) => any) {
+  return function createRemoteComponent(info: LazyRemoteComponentInfo<T, E>) {
+    LoggerInstance.warn(
+      `createRemoteComponent is deprecated, please use createRemoteAppComponent instead!`,
+    );
+    return createFn(info);
+  };
+}

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

@@ -0,0 +1,104 @@
+import React, { useContext, useEffect, useState, forwardRef } from 'react';
+import * as ReactRouterDOM from 'react-router-dom';
+import { dispatchPopstateEnv } from '@module-federation/bridge-shared';
+import { LoggerInstance, pathJoin } from '../../utils';
+import { RemoteAppWrapper } from '../RemoteAppWrapper';
+
+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);

package/src/remote/router-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/router-component/index.tsx

@@ -0,0 +1,10 @@
+/**
+ * Default entry point with React Router support
+ * Re-exports from router/create.tsx
+ */
+export {
+  createRemoteAppComponent,
+  createRemoteComponent,
+  createLazyRemoteComponent,
+  type LazyRemoteComponentInfo,
+} from './create';

package/src/router/default.tsx

@@ -0,0 +1,73 @@
+import React, { useContext } from 'react';
+// The upper alias react-router-dom$ into this file avoids the loop
+import * as ReactRouterDom from 'react-router-dom/';
+import { RouterContext } from '../provider/context';
+import { LoggerInstance } from '../utils';
+
+function WrapperRouter(
+  props:
+    | Parameters<typeof ReactRouterDom.BrowserRouter>[0]
+    | Parameters<typeof ReactRouterDom.MemoryRouter>[0],
+) {
+  const { basename, ...propsRes } = props;
+  const routerContextProps = useContext(RouterContext) || {};
+
+  LoggerInstance.debug(`WrapperRouter info >>>`, {
+    ...routerContextProps,
+    routerContextProps,
+    WrapperRouterProps: props,
+  });
+
+  if (routerContextProps?.memoryRoute) {
+    return (
+      <ReactRouterDom.MemoryRouter
+        {...props}
+        initialEntries={[routerContextProps?.memoryRoute.entryPath]}
+      />
+    );
+  }
+  return (
+    <ReactRouterDom.BrowserRouter
+      {...propsRes}
+      basename={routerContextProps?.basename || basename}
+    />
+  );
+}
+
+function WrapperRouterProvider(
+  props: Parameters<typeof ReactRouterDom.RouterProvider>[0],
+) {
+  const { router, ...propsRes } = props;
+  const routerContextProps = useContext(RouterContext) || {};
+  const routers = router.routes;
+  LoggerInstance.debug(`WrapperRouterProvider info >>>`, {
+    ...routerContextProps,
+    routerContextProps,
+    WrapperRouterProviderProps: props,
+    router,
+  });
+  const RouterProvider = (ReactRouterDom as any)['Router' + 'Provider'];
+  const createMemoryRouter = (ReactRouterDom as any)['create' + 'MemoryRouter'];
+  const createBrowserRouter = (ReactRouterDom as any)[
+    'create' + 'BrowserRouter'
+  ];
+
+  if (routerContextProps.memoryRoute) {
+    const MemeoryRouterInstance = createMemoryRouter(routers, {
+      initialEntries: [routerContextProps?.memoryRoute.entryPath],
+    });
+    return <RouterProvider router={MemeoryRouterInstance} />;
+  } else {
+    const BrowserRouterInstance = createBrowserRouter(routers, {
+      basename: routerContextProps.basename || router?.basename,
+      future: router.future,
+      window: router.window,
+    });
+    return <RouterProvider {...propsRes} router={BrowserRouterInstance} />;
+  }
+}
+
+export * from 'react-router-dom/';
+
+export { WrapperRouter as BrowserRouter };
+export { WrapperRouterProvider as RouterProvider };

package/src/router/v5.tsx

@@ -0,0 +1,43 @@
+import React, { useContext } from 'react';
+// The upper alias react-router-dom$ into this file avoids the loop
+// @ts-ignore
+import * as ReactRouterDom from 'react-router-dom/index.js';
+import { RouterContext } from '../provider/context';
+import { LoggerInstance } from '../utils';
+
+function WraperRouter(
+  props:
+    | Parameters<typeof ReactRouterDom.BrowserRouter>[0]
+    | Parameters<typeof ReactRouterDom.MemoryRouter>[0],
+) {
+  const { basename, ...propsRes } = props;
+  const routerContextProps = useContext(RouterContext) || {};
+
+  LoggerInstance.debug(`WraperRouter info >>>`, {
+    ...routerContextProps,
+    routerContextProps,
+    WraperRouterProps: props,
+  });
+
+  if (routerContextProps?.memoryRoute) {
+    return (
+      <ReactRouterDom.MemoryRouter
+        {...props}
+        initialEntries={[routerContextProps?.memoryRoute.entryPath]}
+      />
+    );
+  }
+  return (
+    <ReactRouterDom.BrowserRouter
+      {...propsRes}
+      basename={routerContextProps?.basename || basename}
+    />
+  );
+}
+
+// @ts-ignore
+// because export directly from react-router-dom/index.js will cause build falied.
+// it will be replace by react-router-dom/index.js in building phase
+export * from 'react-router-dom/';
+
+export { WraperRouter as BrowserRouter };

package/src/router/v6.tsx

@@ -0,0 +1,74 @@
+import React, { useContext } from 'react';
+// The upper alias react-router-dom$ into this file avoids the loop
+import * as ReactRouterDom from 'react-router-dom/dist/index.js';
+import { RouterContext } from '../provider/context';
+import { LoggerInstance } from '../utils';
+
+function WraperRouter(
+  props:
+    | Parameters<typeof ReactRouterDom.BrowserRouter>[0]
+    | Parameters<typeof ReactRouterDom.MemoryRouter>[0],
+) {
+  const { basename, ...propsRes } = props;
+  const routerContextProps = useContext(RouterContext) || {};
+
+  LoggerInstance.debug(`WraperRouter info >>>`, {
+    ...routerContextProps,
+    routerContextProps,
+    WraperRouterProps: props,
+  });
+
+  if (routerContextProps?.memoryRoute) {
+    return (
+      <ReactRouterDom.MemoryRouter
+        {...props}
+        initialEntries={[routerContextProps?.memoryRoute.entryPath]}
+      />
+    );
+  }
+  return (
+    <ReactRouterDom.BrowserRouter
+      {...propsRes}
+      basename={routerContextProps?.basename || basename}
+    />
+  );
+}
+
+function WraperRouterProvider(
+  props: Parameters<typeof ReactRouterDom.RouterProvider>[0],
+) {
+  const { router, ...propsRes } = props;
+  const routerContextProps = useContext(RouterContext) || {};
+  const routers = router.routes;
+  LoggerInstance.debug(`WraperRouterProvider info >>>`, {
+    ...routerContextProps,
+    routerContextProps,
+    WraperRouterProviderProps: props,
+    router,
+  });
+  const RouterProvider = (ReactRouterDom as any)['Router' + 'Provider'];
+  const createMemoryRouter = (ReactRouterDom as any)['create' + 'MemoryRouter'];
+  const createBrowserRouter = (ReactRouterDom as any)[
+    'create' + 'BrowserRouter'
+  ];
+
+  if (routerContextProps.memoryRoute) {
+    const MemeoryRouterInstance = createMemoryRouter(routers, {
+      initialEntries: [routerContextProps?.memoryRoute.entryPath],
+    });
+    return <RouterProvider router={MemeoryRouterInstance} />;
+  } else {
+    const BrowserRouterInstance = createBrowserRouter(routers, {
+      // In host app, the routerContextProps is {}, so we should use router.basename as fallback
+      basename: routerContextProps.basename || router.basename,
+      future: router.future,
+      window: router.window,
+    });
+    return <RouterProvider {...propsRes} router={BrowserRouterInstance} />;
+  }
+}
+
+// export * from 'react-router-dom/dist/index.js';
+export * from 'react-router-dom/';
+export { WraperRouter as BrowserRouter };
+export { WraperRouterProvider as RouterProvider };

package/src/router/v7.tsx

@@ -0,0 +1,75 @@
+import React, { useContext } from 'react';
+// The upper alias react-router$ into this file avoids the loop
+// React Router v7 uses different dist structure, we'll import from the main entry
+import * as ReactRouterDom from 'react-router';
+import { RouterContext } from '../provider/context';
+import { LoggerInstance } from '../utils';
+
+function WraperRouter(
+  props:
+    | Parameters<typeof ReactRouterDom.BrowserRouter>[0]
+    | Parameters<typeof ReactRouterDom.MemoryRouter>[0],
+) {
+  const { basename, ...propsRes } = props;
+  const routerContextProps = useContext(RouterContext) || {};
+
+  LoggerInstance.debug(`WraperRouter info >>>`, {
+    ...routerContextProps,
+    routerContextProps,
+    WraperRouterProps: props,
+  });
+
+  if (routerContextProps?.memoryRoute) {
+    return (
+      <ReactRouterDom.MemoryRouter
+        {...props}
+        initialEntries={[routerContextProps?.memoryRoute.entryPath]}
+      />
+    );
+  }
+  return (
+    <ReactRouterDom.BrowserRouter
+      {...propsRes}
+      basename={routerContextProps?.basename || basename}
+    />
+  );
+}
+
+function WraperRouterProvider(
+  props: Parameters<typeof ReactRouterDom.RouterProvider>[0],
+) {
+  const { router, ...propsRes } = props;
+  const routerContextProps = useContext(RouterContext) || {};
+  const routers = router.routes;
+  LoggerInstance.debug(`WraperRouterProvider info >>>`, {
+    ...routerContextProps,
+    routerContextProps,
+    WraperRouterProviderProps: props,
+    router,
+  });
+  const RouterProvider = (ReactRouterDom as any)['Router' + 'Provider'];
+  const createMemoryRouter = (ReactRouterDom as any)['create' + 'MemoryRouter'];
+  const createBrowserRouter = (ReactRouterDom as any)[
+    'create' + 'BrowserRouter'
+  ];
+
+  if (routerContextProps.memoryRoute) {
+    const MemeoryRouterInstance = createMemoryRouter(routers, {
+      initialEntries: [routerContextProps?.memoryRoute.entryPath],
+    });
+    return <RouterProvider router={MemeoryRouterInstance} />;
+  } else {
+    const BrowserRouterInstance = createBrowserRouter(routers, {
+      // In host app, the routerContextProps is {}, so we should use router.basename as fallback
+      basename: routerContextProps.basename || router.basename,
+      future: router.future,
+      window: router.window,
+    });
+    return <RouterProvider {...propsRes} router={BrowserRouterInstance} />;
+  }
+}
+
+// Export all from react-router for v7 compatibility
+export * from 'react-router';
+export { WraperRouter as BrowserRouter };
+export { WraperRouterProvider as RouterProvider };

package/src/types.ts

@@ -0,0 +1,147 @@
+import * as React from 'react';
+import { ErrorBoundaryPropsWithComponent } from 'react-error-boundary';
+
+/**
+ * Options for creating a React root
+ */
+export interface CreateRootOptions {
+  identifierPrefix?: string;
+  onRecoverableError?: (error: unknown) => void;
+  transitionCallbacks?: unknown;
+}
+
+/**
+ * Interface for a React root object
+ */
+export interface Root {
+  render(children: React.ReactNode): void;
+  unmount(): void;
+}
+
+/**
+ * Type for a root element, which can be either an HTMLElement or a React root
+ */
+export type RootType = HTMLElement | Root;
+
+/**
+ * Parameters for the render function
+ */
+export interface RenderParams {
+  moduleName?: string;
+  basename?: string;
+  memoryRoute?: {
+    entryPath: string;
+    initialState?: Record<string, unknown>;
+  };
+  dom: HTMLElement;
+  /**
+   * Options to pass to createRoot for React 18 and 19
+   * @example
+   * {
+   *   identifierPrefix: 'app-',
+   *   onRecoverableError: (err) => console.error(err)
+   * }
+   */
+  rootOptions?: CreateRootOptions;
+  [key: string]: unknown;
+}
+
+/**
+ * Parameters for the destroy function
+ */
+export interface DestroyParams {
+  moduleName: string;
+  dom: HTMLElement;
+}
+
+/**
+ * Parameters for the provider function
+ */
+export interface ProviderParams {
+  moduleName?: string;
+  basename?: string;
+  memoryRoute?: {
+    entryPath: string;
+    initialState?: Record<string, unknown>;
+  };
+  style?: React.CSSProperties;
+  className?: string;
+}
+
+/**
+ * Parameters for the render function, extending ProviderParams
+ */
+export interface RenderFnParams extends ProviderParams {
+  dom: HTMLElement;
+  fallback?: React.ComponentType<{ error: Error }>;
+  [key: string]: unknown;
+}
+
+/**
+ * Parameters for the provider function
+ */
+export interface ProviderFnParams<T> {
+  rootComponent: React.ComponentType<T>;
+  render?: (
+    App: React.ReactElement,
+    id?: HTMLElement | string,
+  ) => RootType | Promise<RootType>;
+  createRoot?: (
+    container: Element | DocumentFragment,
+    options?: CreateRootOptions,
+  ) => Root;
+  /**
+   * Default options to pass to createRoot for React 18 and 19
+   * These options will be used when creating a root unless overridden by rootOptions in render params
+   * @example
+   * {
+   *   identifierPrefix: 'app-',
+   *   onRecoverableError: (err) => console.error(err)
+   * }
+   */
+  defaultRootOptions?: CreateRootOptions;
+}
+
+/**
+ * Parameters for the remote component
+ */
+export interface RemoteComponentProps<T = Record<string, unknown>> {
+  props?: T;
+  fallback?: React.ComponentType<{ error: Error }>;
+  loading?: React.ReactNode;
+  [key: string]: unknown;
+}
+
+/**
+ * Parameters for the remote component loader
+ */
+export interface RemoteComponentParams<
+  T = Record<string, unknown>,
+  E extends keyof T = keyof T,
+> {
+  loader: () => Promise<T>;
+  loading: React.ReactNode;
+  fallback: React.ComponentType<{ error: Error }>;
+  export?: E;
+  props?: T;
+}
+
+/**
+ * Interface for a remote module provider
+ */
+export interface RemoteModule {
+  provider: () => {
+    render: (info: RenderFnParams) => void;
+    destroy: (info: { dom: any }) => void;
+  };
+}
+
+/**
+ * Parameters for a remote app component
+ */
+export interface RemoteAppParams extends ProviderParams {
+  moduleName: string;
+  providerInfo: NonNullable<RemoteModule['provider']>;
+  exportName: string | number | symbol;
+  fallback: ErrorBoundaryPropsWithComponent['FallbackComponent'];
+}