React Bridge

@module-federation/bridge-react 提供了用于 React 应用的 bridge 工具函数：

createBridgeComponent：用于导出应用级别模块，适用于生产者包装其作为应用类型导出的模块
createRemoteComponent：用于加载应用级别模块，适用于消费者加载作为应用类型加载的模块

安装

npm

yarn

pnpm

npm install @module-federation/bridge-react@latest

示例

导出应用类型模块

DANGER

请注意：使用 @module-federation/bridge-react 后不能将 react-router-dom 设置成 shared，否则构建工具将会提示异常。这是因为 @module-federation/bridge-react 通过代理 react-router-dom 实现了对路由的控制，以保证应用间路由能够正常协同工作。

在生产者项目中，假设我们需要将应用通过 @module-federation/bridge-react 导出为一个应用类型模块，应用入口为 App.tsx 文件

Step1: 首先，我们新建一个文件 export-app.tsx，该文件将作为应用类型模块导出的文件。我们需要使用 createBridgeComponent 来包装应用的根组件。

// ./src/export-app.tsx
import App from './src/App.tsx';
import { createBridgeComponent } from '@module-federation/bridge-react';

export default createBridgeComponent({
  rootComponent: App
});

Step2: 在 rsbuild.config.ts 配置文件中，我们需要将 export-app.tsx 作为应用类型模块导出

// rsbuild.config.ts
import { pluginModuleFederation } from '@module-federation/rsbuild-plugin';

export default defineConfig({
  plugins: [
    pluginReact(),
    pluginModuleFederation({
      name: 'remote1',
      exposes: {
        './export-app': './src/export-app.tsx',
      },
      shared: ['react', 'react-dom'],
    }),
  ],
});

至此，我们完成了应用类型模块的导出。

INFO

为什么应用类型模块需要使用 createBridgeComponent 包装？原因主要有三点：

支持跨框架渲染。通过 createBridgeComponent 包装的组件将符合应用类型消费方的加载协议，这使得跨框架渲染成为可能
自动注入 basename。通过 createBridgeComponent 包装的组件将自动注入 basename，这能保证生产者应用在消费者项目下也能正常工作
包裹 ErrorBoundary。通过 createBridgeComponent 包装的组件将包裹 ErrorBoundary，以保证在远程加载失败或渲染出错时，能够自动进入兜底逻辑

加载应用类型模块

Host

Step1: 在 rsbuild.config.ts 配置中，我们需要注册远程模块，这点与其它 Module Federation 配置无异。

// rsbuild.config.ts
export default defineConfig({
  plugins: [
    pluginReact(),
    pluginModuleFederation({
      name: 'host',
      remotes: {
        remote1: 'remote1@http://localhost:2001/mf-manifest.json',
      },
    }),
  ],
});

Step2: 在消费者项目中，我们需要加载应用类型模块，我们使用 createRemoteComponent 来加载应用类型模块

// ./src/App.tsx
import React from 'react';
import { createRemoteComponent } from '@module-federation/bridge-react';
import styles from './index.module.less';

// 定义 FallbackErrorComp 组件
const FallbackErrorComp = ({ error, resetErrorBoundary }) => {
  return (
    <div>
      <h2>This is ErrorBoundary Component</h2>
      <p>Something went wrong:</p>
      <pre style={{ color: 'red' }}>{error.message}</pre>
      <button onClick={() => resetErrorBoundary()}>
        resetErrorBoundary(try again)
      </button>
    </div>
  );
};

// 定义 FallbackLoading 组件
const FallbackComp = <div data-test-id="loading">loading...</div>;

// 使用 createRemoteComponent 创建远程组件
const Remote1App = createRemoteComponent({
  // loader 用于加载远程模块，例如：loadRemote('remote1/export-app')、import('remote1/export-app')
  loader: () => loadRemote('remote1/export-app'),
  // fallback 用于在加载远程模块失败时展示的组件
  fallback: FallbackErrorComp,
  // loading 用于在加载远程模块时展示的组件
  loading: FallbackComp,
});

const App = () => {
  return (
    <BrowserRouter basename="/">
      <Routes>
        <Route path="/" Component={Home} />
        <Route
          path="/remote1/*"
          // 使用 Remote1App 组件, 将会被懒加载
          Component={() => (
            <Remote1App
              // 可设置 className 和 style 样式，将自动注入到组件上
              className={styles.remote1}
              style={{ color: 'red' }}
              // name 和 age 为远程组件 props, 将自动透传到远程组件
              name={'Ming'}
              age={12}
              // 可设置 ref, 将自动转发到远程组件，可获取 ref 对象操作 dom
              ref={ref}
              // 通过 memoryRoute 来将子应用路由控制为 memoryRouter，将不会直接将 url 展示在浏览器地址上
              memoryRoute={{ entryPath: '/detail' }}
            />
          )}
        />
      </Routes>
    </BrowserRouter>
  );
};

至此，我们完成了应用类型模块的加载。

INFO

通过 createRemoteComponent 导出的远程模块将会自动使用 react-bridge 加载协议加载模块，这使得应用的跨框架渲染成为可能。
此外，createRemoteComponent 会自动处理模块加载、模块销毁、错误处理、loading、路由等逻辑，开发者只需要关注如何使用远程组件即可。
通过 createRemoteComponent 导出的远程模块，你可以像使用普通 React 组件一样使用远程组件：传递 className、style、props、ref 等属性均会自动透传到远程组件, 这使得用户在体验上几乎等同于使用本地组件

API 参考

createBridgeComponent

createBridgeComponent 用于将 React 组件包装成可远程加载的模块。

/**
 * 创建一个可远程加载的 React 组件
 * @param bridgeInfo - Bridge Component Config information
 * @returns 返回一个函数，该函数返回包含 render 和 destroy 方法的对象
 */
function createBridgeComponent<T>(
  bridgeInfo: ProviderFnParams<T>
): () => {
  render(info: RenderFnParams): Promise<void>;
  destroy(info: DestroyParams): Promise<void>;
};

/**
 * 桥接组件配置信息
 */
interface ProviderFnParams<T> {
  /** 需要被远程加载的根组件 */
  rootComponent: React.ComponentType<T>;
  
  /** 
   * 自定义渲染函数，用于自定义渲染逻辑
   * @param App - React 元素
   * @param id - DOM 元素或字符串 ID
   * @returns React 根元素或 Promise
   */
  render?: (
    App: React.ReactElement,
    id?: HTMLElement | string,
  ) => RootType | Promise<RootType>;
  
  /**
   * 自定义创建 React 根节点的函数
   * @param container - 容器元素
   * @param options - 创建根节点的选项
   * @returns React 根节点
   */
  createRoot?: (
    container: Element | DocumentFragment,
    options?: CreateRootOptions,
  ) => Root;
}

/**
 * 创建 React 根节点的选项
 */
interface CreateRootOptions {
  /** 为生成的 React ID 添加前缀，用于避免 ID 冲突 */
  identifierPrefix?: string;
  
  /** 处理 React 在渲染过程中可恢复的错误的回调函数 */
  onRecoverableError?: (error: unknown) => void;
  
  /** 过渡回调函数，用于 React 18 的并发特性 */
  transitionCallbacks?: TransitionCallbacks;
}

createRemoteComponent

createRemoteComponent 用于加载远程 React 组件。

/**
 * 创建远程 React 组件
 * @param options - 远程组件配置选项
 * @returns 返回一个 React 组件，可以接收 props 并渲染远程组件
 */
function createRemoteComponent<T, E extends keyof T = 'default'>(
  options: RemoteComponentParams<T, E>
): React.ForwardRefExoticComponent<
  React.PropsWithoutRef<RemoteComponentProps> & React.RefAttributes<HTMLDivElement>
>;

/**
 * 远程组件配置参数
 */
interface RemoteComponentParams<
  T = Record<string, unknown>,
  E extends keyof T = keyof T
> {
  /** 
   * 加载远程模块的函数
   * 例如：() => loadRemote('remote1/export-app') 或 () => import('remote1/export-app')
   */
  loader: () => Promise<T>;
  
  /** 加载远程模块时显示的组件 */
  loading: React.ReactNode;
  
  /** 加载或渲染远程模块失败时显示的错误组件 */
  fallback: React.ComponentType<{ error: Error }>;
  
  /** 
   * 指定模块的导出名称
   * 默认为 'default'
   */
  export?: E;
}

/**
 * 远程组件属性
 */
interface RemoteComponentProps<T = Record<string, unknown>> {
  /** 传递给远程组件的属性 */
  props?: T;

  /** 
   * 内存路由配置，用于将子应用路由控制为 memoryRouter
   * 将不会直接将 URL 展示在浏览器地址栏上
   */
  memoryRoute?: { entryPath: string };
  
  /** 基础路径名 */
  basename?: string;
  
  /** 样式 */
  style?: React.CSSProperties;
  
  /** 类名 */
  className?: string;
}

使用示例

使用 export 指定模块导出

// remote
export const provider = createBridgeComponent({
  rootComponent: App
});

// host
const Remote1App = createRemoteComponent({
  loader: () => loadRemote('remote1/export-app'),
  export: 'provider', // 指定使用 provider 导出
  fallback: FallbackErrorComp,
  loading: FallbackComp,
});

使用 memoryRoute 控制路由

function App() {
  return (
    <BrowserRouter basename="/">
      <Routes>
        <Route
          path="/remote1/*"
          Component={() => (
            <Remote1App
              className={styles.remote1}
              style={{ color: 'red' }}
              // 通过 memoryRoute 来将子应用路由控制为 memoryRouter
              // 将不会直接将 URL 展示在浏览器地址栏上
              memoryRoute={{ entryPath: '/detail' }}
              // 其他属性会透传给远程组件
              props1={'props_value'}
              props2={'another_props_value'}
              ref={ref}
            />
          )}
        />
      </Routes>
    </BrowserRouter>
  );
}

ON THIS PAGE

React

Modern.js

Next.js

Angular

React Bridge

安装

示例

导出应用类型模块

加载应用类型模块

API 参考

createBridgeComponent

createRemoteComponent

使用示例

使用 export 指定模块导出

使用 memoryRoute 控制路由

React Bridge#

安装#

示例#

导出应用类型模块#

加载应用类型模块#

API 参考#

createBridgeComponent#

createRemoteComponent#

使用示例#

使用 export 指定模块导出#

使用 memoryRoute 控制路由#

React Bridge

安装

示例

导出应用类型模块

加载应用类型模块

API 参考

createBridgeComponent

createRemoteComponent

使用示例

使用 export 指定模块导出

使用 memoryRoute 控制路由