指南
实践
配置
插件
案例
博客
生态
指南
实践
配置
插件
案例
博客
简体中文

导出应用

本章将介绍如何使用 createBridgeComponent 将您的 React 应用导出为可被远程加载的模块。

安装

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

基本使用

步骤 1: 创建导出入口

要导出一个 React 应用，您需要创建一个专门的导出文件，使用 createBridgeComponent 将应用包装为远程模块。

假设您的应用入口是 App.tsx，创建一个新文件 export-app.tsx：

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

// 使用 createBridgeComponent 将 App 包装为远程模块并导出
export default createBridgeComponent({
  rootComponent: App
});

步骤 2: 配置 exposes 导出

接下来需要在构建工具中配置 Module Federation，将创建的导出文件暴露给其他应用使用。

构建工具支持

以下示例使用 Rsbuild 配置，请根据您使用的构建工具进行相应调整：

  • Rsbuild: @module-federation/rsbuild-plugin
  • Rspack: @module-federation/enhanced/rspack
  • Webpack: @module-federation/enhanced/webpack
  • Vite: @module-federation/vite
// rsbuild.config.ts
import { pluginModuleFederation } from '@module-federation/rsbuild-plugin';

export default {
  plugins: [
    pluginModuleFederation({
      name: 'remote1',
      exposes: {
        './export-app': './src/export-app.tsx', // 导出应用类型远程模块
      },
    }),
  ],
};

Bridge Router 配置

React Bridge 提供了强大的路由协同能力，可根据当前路径动态为应用注入 basename 和路由上下文传递。

路由框架支持

  • Bridge Router 目前支持 React Router v5、v6、v7 版本的路由代理功能。

  • 暂不支持其他路由框架如 @tanstack/react-router，针对非 React Router 的应用，需要显示关闭 enableBridgeRouter，并自行处理路由逻辑。

启用 Bridge Router

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

export default {
  plugins: [
    pluginModuleFederation({
      name: 'remote1',
      exposes: {
        './export-app': './src/export-app.tsx',
      },
      bridge: {
        // 启用 Bridge Router 路由能力，默认为 true
        enableBridgeRouter: true, 
      }
    }),
  ],
};

配置说明

  • enableBridgeRouter: true (默认值) - 自动处理 basename 和路由协同，支持 React Router v5、v6、v7
  • enableBridgeRouter: false - 禁用 Bridge 默认的路由代理能力，用户需手动处理路由集成
重要

启用 Bridge Router 时，请勿将 react-router-dom 配置为 shared 依赖，否则会导致路由功能异常。

createBridgeComponent API 参考

函数签名

function createBridgeComponent<T = any>(
  bridgeInfo: Omit<ProviderFnParams<T>, 'createRoot'>
): () => {
  render(info: RenderParams): Promise<void>;
  destroy(info: DestroyParams): void;
}

ProviderFnParams<T>

桥接组件的配置参数：

interface ProviderFnParams<T> {
  // 根组件
  rootComponent: React.ComponentType<T>;
  
  // 自定义渲染函数（可选）
  render?: (App: React.ReactElement, id?: HTMLElement | string) => RootType | Promise<RootType>;
  
  // 自定义 createRoot 函数（可选，React 18+）
  createRoot?: (container: Element | DocumentFragment, options?: CreateRootOptions) => Root;
  
  // 默认的 createRoot 选项（React 18+）
  defaultRootOptions?: CreateRootOptions;
}

RenderParams

渲染参数接口：

interface RenderParams {
  moduleName?: string;
  basename?: string;
  memoryRoute?: {
    entryPath: string;
    initialState?: Record<string, unknown>;
  };
  dom: HTMLElement;                    // 渲染目标 DOM 元素
  rootOptions?: CreateRootOptions;     // React 18+ 的 createRoot 选项
  [key: string]: unknown;             // 其他自定义属性
}

DestroyParams

销毁参数接口：

interface DestroyParams {
  moduleName: string;
  dom: HTMLElement;
}

CreateRootOptions

React 18+ 的 createRoot 选项：

interface CreateRootOptions {
  identifierPrefix?: string;                                    // 标识符前缀
  onRecoverableError?: (error: unknown) => void;              // 可恢复错误处理
  transitionCallbacks?: unknown;                               // 过渡回调
}

高级用法示例

自定义渲染逻辑

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

export default createBridgeComponent({
  rootComponent: App,
  
  // 自定义渲染函数
  render: (App, container) => {
    const root = createRoot(container as HTMLElement, {
      identifierPrefix: 'my-app-'
    });
    root.render(App);
    return root;
  },
  
  // 默认的 createRoot 选项
  defaultRootOptions: {
    identifierPrefix: 'remote-app-',
    onRecoverableError: (error) => {
      console.error('Remote app recoverable error:', error);
    }
  }
});

支持多个导出

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

// 导出主应用
export default createBridgeComponent({
  rootComponent: App
});

// 导出仪表板组件
export const dashboard = createBridgeComponent({
  rootComponent: Dashboard
});

对应的 Module Federation 配置：

// rsbuild.config.ts
export default {
  plugins: [
    pluginModuleFederation({
      name: 'remote1',
      exposes: {
        './export-app': './src/export-app.tsx',     // 主应用
        './dashboard': './src/export-app.tsx',      // 仪表板
      },
    }),
  ],
};

下一步

导出应用配置完成后，您可以继续阅读 加载远程应用 来了解如何在宿主应用中加载这个远程应用。