@ice/mf-runtime 1.0.2-beta.3 → 1.0.3-beta.1

package/README.md

@@ -1,12 +1,18 @@
 # @ice/mf-runtime
 
-基于 Module Federation 的运行时工具，用于在 ice.js 应用中加载和管理远程模块。支持跨版本 React 组件加载
+基于 Module Federation 的运行时工具，用于在 ice.js 应用中加载和管理远程模块。支持跨版本 React 组件加载，并提供增强的插件机制。
 
 ## 特性
 
 - 基于 [Module Federation 2.0](https://module-federation.io/index.html)
 - 支持跨版本 React 组件加载
 - 内置冲突检测和降级渲染
+- 🔌 **增强插件机制**: 完全兼容标准 MF 运行时插件
+- 🎯 **组件增强**: 支持 HOC、Props 注入等组件扩展机制  
+- 🛡️ **错误边界**: 内置错误处理和恢复机制
+- 📊 **性能监控**: 支持组件加载和渲染性能追踪
+- 🔄 **热插拔**: 运行时动态注册和移除插件
+- 📝 **TypeScript**: 完整的类型定义支持
 
 ## 安装
 
@@ -14,6 +20,220 @@
 $ npm i @ice/mf-runtime --save
 ```
 
+## 插件机制
+
+从 v1.0.1 开始，`@ice/mf-runtime` 支持强大的插件机制，允许在运行时动态扩展微前端功能。
+
+### 插件类型
+
+#### 1. 标准 MF 插件 (FederationRuntimePlugin)
+标准 MF 插件使用原生的 `@module-federation/runtime` API 进行管理：
+
+```typescript
+import { registerPlugins } from '@module-federation/runtime';
+import type { FederationRuntimePlugin } from '@ice/mf-runtime';
+
+const mfPlugin: FederationRuntimePlugin = {
+  name: 'my-mf-plugin',
+  beforeRequest: (args) => {
+    console.log('模块请求前:', args);
+    return args;
+  },
+  onLoad: (args) => {
+    console.log('模块加载后:', args);
+    return args;
+  },
+  afterResolve: (args) => {
+    console.log('模块解析后:', args);
+    return args;
+  }
+};
+
+// 使用原生 API 注册标准 MF 插件
+registerPlugins([mfPlugin]);
+```
+
+#### 2. 增强插件 (EnhancedRuntimePlugin)
+增强插件使用新的 API 进行管理，提供组件级别的扩展能力：
+
+```typescript
+import { registerEnhancedPlugins } from '@ice/mf-runtime';
+import type { EnhancedRuntimePlugin } from '@ice/mf-runtime';
+
+const enhancedPlugin: EnhancedRuntimePlugin = {
+  name: 'my-enhanced-plugin',
+  
+  // 组件包装器 - 支持 HOC 模式
+  wrapComponent: (WrappedComponent, context) => {
+    return function Enhanced(props) {
+      console.log(`渲染组件: ${context.remoteName}/${context.moduleName}`);
+      return <WrappedComponent {...props} />;
+    };
+  },
+  
+  // 属性注入器
+  injectProps: (props, context) => {
+    return {
+      ...props,
+      injectedProp: `来自 ${context.remoteName} 的数据`
+    };
+  }
+};
+
+// 使用新的 API 注册增强插件
+registerEnhancedPlugins([enhancedPlugin]);
+```
+
+### 注册和使用插件
+
+#### 基本用法
+
+```typescript
+import { init, registerEnhancedPlugins, RemoteModule } from '@ice/mf-runtime';
+import { registerPlugins } from '@module-federation/runtime';
+
+// 注册标准 MF 插件
+registerPlugins([mfPlugin]);
+
+// 注册增强插件
+registerEnhancedPlugins([enhancedPlugin]);
+
+// 初始化运行时
+init({
+  remotes: [
+    {
+      name: 'remote-app',
+      entry: 'http://localhost:3001/remoteEntry.js'
+    }
+  ]
+});
+
+// 使用远程模块（插件会自动应用）
+function App() {
+  return (
+    <RemoteModule
+      scope="remote-app"
+      module="Button"
+      componentProps={{ text: '点击我' }}
+    />
+  );
+}
+```
+
+#### 使用示例插件包
+
+我们提供了一个示例插件包 `@ice/mf-plugin-example`，包含常用的插件：
+
+```bash
+npm install @ice/mf-plugin-example
+```
+
+```typescript
+import { registerPlugins } from '@module-federation/runtime';
+import { registerEnhancedPlugins } from '@ice/mf-runtime';
+import { 
+  errorBoundaryPlugin, 
+  commonPropsPlugin, 
+  developmentMFLoggingPlugin,
+  developmentEnhancedLoggingPlugin 
+} from '@ice/mf-plugin-example';
+
+// 注册标准 MF 插件
+registerPlugins([
+  developmentMFLoggingPlugin  // MF 日志插件
+]);
+
+// 注册增强插件
+registerEnhancedPlugins([
+  developmentEnhancedLoggingPlugin,  // 增强日志插件
+  errorBoundaryPlugin,               // 错误边界插件  
+  commonPropsPlugin                  // 通用属性注入插件
+]);
+```
+
+### 插件开发指南
+
+#### 错误边界插件示例
+
+```typescript
+import { ErrorBoundary } from 'react-error-boundary';
+
+const errorBoundaryPlugin: EnhancedRuntimePlugin = {
+  name: 'error-boundary',
+  wrapComponent: (WrappedComponent, context) => {
+    return function ErrorBoundaryWrapper(props) {
+      return (
+        <ErrorBoundary
+          fallback={<div>组件 {context.remoteName} 加载失败</div>}
+          onError={(error) => {
+            console.error(`组件错误:`, error);
+          }}
+        >
+          <WrappedComponent {...props} />
+        </ErrorBoundary>
+      );
+    };
+  }
+};
+```
+
+#### 属性注入插件示例
+
+```typescript
+const themePlugin: EnhancedRuntimePlugin = {
+  name: 'theme-injector',
+  injectProps: (props, context) => {
+    return {
+      ...props,
+      theme: {
+        mode: 'light',
+        primaryColor: '#1890ff'
+      }
+    };
+  }
+};
+```
+
+### 插件 API
+
+#### EnhancedPluginManager
+
+```typescript
+import { getEnhancedPluginManager } from '@ice/mf-runtime';
+
+const manager = getEnhancedPluginManager();
+
+// 注册增强插件
+manager.register(enhancedPlugin);
+
+// 获取插件信息
+const info = manager.getPluginInfo();
+// 返回: [{ name: 'plugin-name', hasWrapper: true, hasInjector: false }]
+
+// 移除插件
+manager.removePlugin('plugin-name');
+
+// 清空所有插件
+manager.clear();
+```
+
+#### React Hook
+
+```typescript
+import { useEnhancedPluginManager } from '@ice/mf-runtime';
+
+function MyComponent() {
+  const enhancedPluginManager = useEnhancedPluginManager();
+  
+  // 动态操作插件
+  const handleAddPlugin = () => {
+    enhancedPluginManager.register(newEnhancedPlugin);
+  };
+  
+  return <div>...</div>;
+}
+```
+
 ## 使用
 
 ### 1. 初始化配置

package/es2017/RemoteModule.js

@@ -2,10 +2,13 @@ import { _ as _object_spread } from "@swc/helpers/_/_object_spread";
 import { loadRemote } from '@module-federation/runtime';
 import * as React from 'react';
 import { useMemo, useState, useLayoutEffect, forwardRef } from 'react';
+import * as ReactDOM from 'react-dom';
 import { ErrorBoundary } from 'react-error-boundary';
 import { FallBack } from './FallBack';
 import { setFederatedModulePublicPath } from './set-public-path';
 import { getMicroMod } from './mf-global-store';
+import { useEnhancedPluginManager } from './plugin-manager';
+import { isRuntimePluginWrapper } from './types';
 const useMountNode = (mountNodeConfig)=>{
     const [resolvedNode, setResolvedNode] = useState(undefined);
     // 解析各种类型的 mountNode
@@ -35,6 +38,7 @@ const RemoteModuleInner = ({ module, scope, runtime, publicPath, LoadingComponen
     var _microMod, _runtime, _runtime1;
     const microMod = getMicroMod(scope);
     const resolvedMountNode = useMountNode(mountNode);
+    const enhancedPluginManager = useEnhancedPluginManager();
     if ((_microMod = microMod) === null || _microMod === void 0 ? void 0 : _microMod.publicPath) {
         setFederatedModulePublicPath(microMod.moduleFederatedName, microMod.publicPath);
     }
@@ -45,35 +49,76 @@ const RemoteModuleInner = ({ module, scope, runtime, publicPath, LoadingComponen
         if (!module || !scope) return null;
         return /*#__PURE__*/ React.lazy(async ()=>{
             var _typedRemoteModule;
+            // 使用标准 MF 加载逻辑，MF 插件自动执行
             const remoteModule = await loadRemote(`${scope}/${module}`);
-            // 检查是否是来自 runtime plugin 的包装函数（通过标记识别）
-            if (typeof remoteModule === 'function' && remoteModule.__ICE_MF_RUNTIME_WRAPPER__) {
-                // 调用包装函数并传入 mountNode 和 containerClassName
-                const ComponentFromPlugin = remoteModule(resolvedMountNode, fallbackContainerClassName);
+            // 使用清晰的对象结构检查是否为 Runtime Plugin 包装器
+            if (isRuntimePluginWrapper(remoteModule)) {
+                // 提取原始组件、运行时信息和 React 实例
+                const { originalComponent, runtimeInfo, reactInstances } = remoteModule();
+                const remoteReact = reactInstances.react;
+                const remoteReactDOM = reactInstances.reactDOM;
+                // 🔑 正确的 HOC 层级顺序：
+                // 1. 先应用增强插件（与其他情况保持一致）
+                const PluginWrappedComponent = enhancedPluginManager.wrapComponent(originalComponent, {
+                    remoteName: scope,
+                    moduleName: module,
+                    props: componentProps || {},
+                    React: remoteReact,
+                    ReactDOM: remoteReactDOM
+                });
+                // 2. 再应用 FallBack（处理不同 React 版本和 mountNode）
+                const FinalComponent = FallBack({
+                    Original: PluginWrappedComponent,
+                    remoteVersion: runtimeInfo.remoteVersion ? ()=>runtimeInfo.remoteVersion : undefined,
+                    hostVersion: runtimeInfo.hostVersion ? ()=>runtimeInfo.hostVersion : undefined,
+                    remoteReactDOM: runtimeInfo.remoteReactDOM,
+                    remoteReact: runtimeInfo.remoteReact,
+                    mountNode: resolvedMountNode,
+                    containerClassName: fallbackContainerClassName
+                });
                 return {
-                    default: ComponentFromPlugin
+                    default: FinalComponent
                 };
             }
             const typedRemoteModule = remoteModule;
+            let BaseComponent;
             if (!((_typedRemoteModule = typedRemoteModule) === null || _typedRemoteModule === void 0 ? void 0 : _typedRemoteModule.default)) {
-                return {
-                    default: remoteModule
-                };
+                BaseComponent = remoteModule;
+            } else {
+                BaseComponent = typedRemoteModule.default;
             }
+            let FinalComponent;
+            // 如果需要 runtime 处理（不同 React 版本或 mountNode）
             if (runtime) {
                 const { react, reactDOM } = runtime;
-                return {
-                    default: FallBack({
-                        Original: typedRemoteModule.default,
-                        remoteReact: ()=>react,
-                        remoteReactDOM: ()=>reactDOM,
-                        mountNode: resolvedMountNode,
-                        containerClassName: fallbackContainerClassName
-                    })
-                };
+                // 先应用增强插件的组件包装器，然后传给 FallBack
+                const PluginWrappedComponent = enhancedPluginManager.wrapComponent(BaseComponent, {
+                    remoteName: scope,
+                    moduleName: module,
+                    props: componentProps || {},
+                    React: react,
+                    ReactDOM: reactDOM
+                });
+                FinalComponent = FallBack({
+                    Original: PluginWrappedComponent,
+                    remoteReact: ()=>react,
+                    remoteReactDOM: ()=>reactDOM,
+                    mountNode: resolvedMountNode,
+                    containerClassName: fallbackContainerClassName
+                });
+            } else {
+                // 没有 runtime 需求时，直接应用插件包装器
+                FinalComponent = enhancedPluginManager.wrapComponent(BaseComponent, {
+                    remoteName: scope,
+                    moduleName: module,
+                    props: componentProps || {},
+                    React: React,
+                    ReactDOM: ReactDOM
+                });
             }
+            console.log('FinalComponent', FinalComponent);
             return {
-                default: typedRemoteModule.default
+                default: FinalComponent
             };
         });
     }, [
@@ -82,11 +127,18 @@ const RemoteModuleInner = ({ module, scope, runtime, publicPath, LoadingComponen
         (_runtime = runtime) === null || _runtime === void 0 ? void 0 : _runtime.react,
         (_runtime1 = runtime) === null || _runtime1 === void 0 ? void 0 : _runtime1.reactDOM,
         resolvedMountNode,
-        fallbackContainerClassName
+        fallbackContainerClassName,
+        enhancedPluginManager,
+        componentProps
     ]);
     const Loading = LoadingComponent || /*#__PURE__*/ React.createElement("div", null, "Loading...");
     const ErrorFallback = ({ error })=>ErrorComponent || /*#__PURE__*/ React.createElement("div", null, "远程模块加载失败: ", error.message);
     if (!Component) return Loading;
+    // 应用增强插件的属性注入
+    const injectedProps = enhancedPluginManager.injectProps(componentProps || {}, {
+        remoteName: scope,
+        moduleName: module
+    });
     return /*#__PURE__*/ React.createElement(ErrorBoundary, {
         resetKeys: [
             module,
@@ -98,8 +150,8 @@ const RemoteModuleInner = ({ module, scope, runtime, publicPath, LoadingComponen
     }, /*#__PURE__*/ React.createElement(React.Suspense, {
         fallback: Loading
     }, /*#__PURE__*/ React.createElement(Component, _object_spread({
-        ref: ref
-    }, componentProps), children)));
+        ref
+    }, injectedProps), children)));
 };
 // 使用 forwardRef 包装组件以支持 ref
 export const RemoteModule = /*#__PURE__*/ forwardRef(RemoteModuleInner);

package/es2017/__tests__/plugin-manager.test.d.ts

@@ -0,0 +1 @@
+export {};

package/es2017/__tests__/plugin-manager.test.js

@@ -0,0 +1,291 @@
+import { _ as _object_spread } from "@swc/helpers/_/_object_spread";
+import { _ as _object_spread_props } from "@swc/helpers/_/_object_spread_props";
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { EnhancedPluginManager, getEnhancedPluginManager, registerEnhancedPlugins } from '../plugin-manager';
+import * as React from 'react';
+describe('EnhancedPluginManager', ()=>{
+    let manager;
+    beforeEach(()=>{
+        manager = new EnhancedPluginManager();
+    });
+    describe('Plugin Registration', ()=>{
+        it('should register an enhanced plugin', ()=>{
+            const enhancedPlugin = {
+                name: 'test-enhanced',
+                wrapComponent: (Component)=>Component,
+                injectProps: (props)=>props
+            };
+            manager.register(enhancedPlugin);
+            const plugins = manager.getPlugins();
+            expect(plugins).toHaveLength(1);
+            expect(plugins[0].name).toBe('test-enhanced');
+        });
+        it('should replace existing plugin with same name', ()=>{
+            const plugin1 = {
+                name: 'test-plugin',
+                wrapComponent: (Component)=>Component
+            };
+            const plugin2 = {
+                name: 'test-plugin',
+                injectProps: (props)=>props
+            };
+            manager.register(plugin1);
+            manager.register(plugin2);
+            const plugins = manager.getPlugins();
+            expect(plugins).toHaveLength(1);
+            expect(plugins[0]).toBe(plugin2);
+        });
+        it('should register multiple plugins', ()=>{
+            const plugins = [
+                {
+                    name: 'plugin1',
+                    wrapComponent: (Component)=>Component
+                },
+                {
+                    name: 'plugin2',
+                    injectProps: (props)=>props
+                }
+            ];
+            manager.registerPlugins(plugins);
+            expect(manager.getPlugins()).toHaveLength(2);
+        });
+    });
+    describe('Component Wrapping', ()=>{
+        it('should wrap component with single plugin', ()=>{
+            const TestComponent = ()=>React.createElement('div', null, 'test');
+            const mockWrapper = vi.fn((Component)=>Component);
+            const plugin = {
+                name: 'wrapper-plugin',
+                wrapComponent: mockWrapper
+            };
+            manager.register(plugin);
+            const context = {
+                remoteName: 'test-remote',
+                moduleName: 'test-module',
+                props: {
+                    test: true
+                },
+                React: React,
+                ReactDOM: undefined
+            };
+            const wrappedComponent = manager.wrapComponent(TestComponent, context);
+            expect(mockWrapper).toHaveBeenCalledWith(TestComponent, context);
+            expect(wrappedComponent).toBe(TestComponent);
+        });
+        it('should apply multiple wrappers in order', ()=>{
+            const TestComponent = ()=>React.createElement('div', null, 'original');
+            const Wrapper1 = ()=>React.createElement('div', null, 'wrapper1');
+            const Wrapper2 = ()=>React.createElement('div', null, 'wrapper2');
+            const plugin1 = {
+                name: 'wrapper1',
+                wrapComponent: ()=>Wrapper1
+            };
+            const plugin2 = {
+                name: 'wrapper2',
+                wrapComponent: ()=>Wrapper2
+            };
+            // 注册顺序很重要
+            manager.register(plugin1);
+            manager.register(plugin2);
+            const context = {
+                remoteName: 'test-remote',
+                moduleName: 'test-module',
+                props: {},
+                React: React,
+                ReactDOM: undefined
+            };
+            const result = manager.wrapComponent(TestComponent, context);
+            // plugin2 应该最后执行，所以返回 Wrapper2
+            expect(result).toBe(Wrapper2);
+        });
+        it('should handle wrapper errors gracefully', ()=>{
+            const TestComponent = ()=>React.createElement('div', null, 'test');
+            const consoleSpy = vi.spyOn(console, 'error').mockImplementation(()=>{});
+            const plugin = {
+                name: 'error-plugin',
+                wrapComponent: ()=>{
+                    throw new Error('Wrapper error');
+                }
+            };
+            manager.register(plugin);
+            const context = {
+                remoteName: 'test-remote',
+                moduleName: 'test-module',
+                props: {},
+                React: React,
+                ReactDOM: undefined
+            };
+            const result = manager.wrapComponent(TestComponent, context);
+            expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('Error applying wrapper from plugin "error-plugin"'), expect.any(Error));
+            expect(result).toBe(TestComponent); // 应该返回原始组件
+            consoleSpy.mockRestore();
+        });
+    });
+    describe('Props Injection', ()=>{
+        it('should inject props with single plugin', ()=>{
+            const mockInjector = vi.fn((props)=>_object_spread_props(_object_spread({}, props), {
+                    injected: true
+                }));
+            const plugin = {
+                name: 'injector-plugin',
+                injectProps: mockInjector
+            };
+            manager.register(plugin);
+            const context = {
+                remoteName: 'test-remote',
+                moduleName: 'test-module'
+            };
+            const result = manager.injectProps({
+                original: true
+            }, context);
+            expect(mockInjector).toHaveBeenCalledWith({
+                original: true
+            }, context);
+            expect(result).toEqual({
+                original: true,
+                injected: true
+            });
+        });
+        it('should apply multiple injectors in order', ()=>{
+            const plugin1 = {
+                name: 'injector1',
+                injectProps: (props)=>_object_spread_props(_object_spread({}, props), {
+                        step1: true
+                    })
+            };
+            const plugin2 = {
+                name: 'injector2',
+                injectProps: (props)=>_object_spread_props(_object_spread({}, props), {
+                        step2: true
+                    })
+            };
+            manager.register(plugin1);
+            manager.register(plugin2);
+            const context = {
+                remoteName: 'test-remote',
+                moduleName: 'test-module'
+            };
+            const result = manager.injectProps({
+                original: true
+            }, context);
+            expect(result).toEqual({
+                original: true,
+                step1: true,
+                step2: true
+            });
+        });
+        it('should handle injection errors gracefully', ()=>{
+            const consoleSpy = vi.spyOn(console, 'error').mockImplementation(()=>{});
+            const plugin = {
+                name: 'error-plugin',
+                injectProps: ()=>{
+                    throw new Error('Injection error');
+                }
+            };
+            manager.register(plugin);
+            const context = {
+                remoteName: 'test-remote',
+                moduleName: 'test-module'
+            };
+            const result = manager.injectProps({
+                original: true
+            }, context);
+            expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('Error injecting props from plugin "error-plugin"'), expect.any(Error));
+            expect(result).toEqual({
+                original: true
+            }); // 应该返回原始props
+            consoleSpy.mockRestore();
+        });
+    });
+    describe('Plugin Management', ()=>{
+        it('should get plugin info', ()=>{
+            const wrapperPlugin = {
+                name: 'wrapper-plugin',
+                wrapComponent: (Component)=>Component
+            };
+            const injectorPlugin = {
+                name: 'injector-plugin',
+                injectProps: (props)=>props
+            };
+            const hybridPlugin = {
+                name: 'hybrid-plugin',
+                wrapComponent: (Component)=>Component,
+                injectProps: (props)=>props
+            };
+            manager.register(wrapperPlugin);
+            manager.register(injectorPlugin);
+            manager.register(hybridPlugin);
+            const info = manager.getPluginInfo();
+            expect(info).toHaveLength(3);
+            expect(info[0]).toEqual({
+                name: 'wrapper-plugin',
+                hasWrapper: true,
+                hasInjector: false
+            });
+            expect(info[1]).toEqual({
+                name: 'injector-plugin',
+                hasWrapper: false,
+                hasInjector: true
+            });
+            expect(info[2]).toEqual({
+                name: 'hybrid-plugin',
+                hasWrapper: true,
+                hasInjector: true
+            });
+        });
+        it('should remove plugin', ()=>{
+            const plugin = {
+                name: 'test-plugin',
+                wrapComponent: (Component)=>Component
+            };
+            manager.register(plugin);
+            expect(manager.getPlugins()).toHaveLength(1);
+            const removed = manager.removePlugin('test-plugin');
+            expect(removed).toBe(true);
+            expect(manager.getPlugins()).toHaveLength(0);
+        });
+        it('should return false when removing non-existent plugin', ()=>{
+            const removed = manager.removePlugin('non-existent');
+            expect(removed).toBe(false);
+        });
+        it('should clear all plugins', ()=>{
+            manager.register({
+                name: 'plugin1',
+                wrapComponent: (Component)=>Component
+            });
+            manager.register({
+                name: 'plugin2',
+                injectProps: (props)=>props
+            });
+            expect(manager.getPlugins()).toHaveLength(2);
+            manager.clear();
+            expect(manager.getPlugins()).toHaveLength(0);
+        });
+    });
+    describe('Global Enhanced Plugin Manager', ()=>{
+        beforeEach(()=>{
+            // 清理全局状态
+            getEnhancedPluginManager().clear();
+        });
+        it('should provide singleton instance', ()=>{
+            const manager1 = getEnhancedPluginManager();
+            const manager2 = getEnhancedPluginManager();
+            expect(manager1).toBe(manager2);
+        });
+        it('should register multiple plugins via convenience function', ()=>{
+            const plugins = [
+                {
+                    name: 'plugin1',
+                    wrapComponent: (Component)=>Component
+                },
+                {
+                    name: 'plugin2',
+                    injectProps: (props)=>props
+                }
+            ];
+            registerEnhancedPlugins(plugins);
+            const manager = getEnhancedPluginManager();
+            expect(manager.getPlugins()).toHaveLength(2);
+        });
+    });
+});

package/es2017/__tests__/setup.d.ts

@@ -0,0 +1 @@
+export {};