简体中文

导出应用

本章将介绍如何使用 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',      // 仪表板
      },
    }),
  ],
};

下一步

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

导出应用

本章将介绍如何使用 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',      // 仪表板
      },
    }),
  ],
};

下一步

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

#导出应用

#安装

#基本使用

#步骤 1: 创建导出入口

#步骤 2: 配置 exposes 导出

#Bridge Router 配置

#启用 Bridge Router

#配置说明

#createBridgeComponent API 参考

#函数签名

#ProviderFnParams<T>

#RenderParams

#DestroyParams

#CreateRootOptions

#高级用法示例

#自定义渲染逻辑

#支持多个导出

#下一步

#导出应用

#安装

#基本使用

#步骤 1: 创建导出入口

#步骤 2: 配置 exposes 导出

#Bridge Router 配置

#启用 Bridge Router

#配置说明

#createBridgeComponent API 参考

#函数签名

#ProviderFnParams<T>

#RenderParams

#DestroyParams

#CreateRootOptions

#高级用法示例

#自定义渲染逻辑

#支持多个导出

#下一步

导出应用

安装

基本使用

步骤 1: 创建导出入口

步骤 2: 配置 `exposes` 导出

Bridge Router 配置

启用 Bridge Router

配置说明

createBridgeComponent API 参考

函数签名

ProviderFnParams<T>

RenderParams

DestroyParams

CreateRootOptions

高级用法示例

自定义渲染逻辑

支持多个导出

下一步

导出应用

安装

基本使用

步骤 1: 创建导出入口

步骤 2: 配置 `exposes` 导出

Bridge Router 配置

启用 Bridge Router

配置说明

createBridgeComponent API 参考

函数签名

ProviderFnParams<T>

RenderParams

DestroyParams

CreateRootOptions

高级用法示例

自定义渲染逻辑

支持多个导出

下一步