@ice/mf-runtime 1.0.3-beta.1 → 1.0.3-beta.2

package/docs/PLUGIN_SYSTEM_GUIDE.md

@@ -0,0 +1,294 @@
+# 微前端插件系统使用指南
+
+## 概述
+
+`@ice/mf-runtime` 提供了一套增强插件系统，允许开发者对远程组件进行功能扩展，如错误边界、日志记录、性能监控等。
+
+## 快速开始
+
+### 1. 安装依赖
+
+```bash
+npm install @ice/mf-runtime
+```
+
+### 2. 基本使用
+
+```tsx
+import { RemoteModule, registerEnhancedPlugins } from '@ice/mf-runtime';
+import { createEnhancedLoggingPlugin } from '@ice/mf-plugin-example';
+
+// 注册插件
+registerEnhancedPlugins([createEnhancedLoggingPlugin()]);
+
+// 使用远程组件
+function App() {
+  return (
+    <RemoteModule
+      scope="remote-app"
+      module="Button"
+    />
+  );
+}
+```
+
+## 插件开发
+
+### 插件接口
+
+```typescript
+export interface EnhancedRuntimePlugin {
+  name: string;
+  wrapComponent?: ComponentWrapper;
+  injectProps?: PropInjector;
+}
+
+export interface ComponentWrapper {
+  (
+    WrappedComponent: React.ComponentType<any>, 
+    context: WrapperContext
+  ): React.ComponentType<any>;
+}
+
+export interface PropInjector {
+  (
+    props: Record<string, any>, 
+    context: InjectionContext
+  ): Record<string, any>;
+}
+```
+
+### 上下文信息
+
+```typescript
+export interface WrapperContext {
+  remoteName: string;
+  moduleName: string;
+  props: Record<string, any>;
+  React: typeof import('react');        // 正确的 React 实例
+  ReactDOM?: typeof import('react-dom'); // 正确的 ReactDOM 实例
+}
+
+export interface InjectionContext {
+  remoteName: string;
+  moduleName: string;
+}
+```
+
+### 创建插件
+
+```typescript
+import type { EnhancedRuntimePlugin, WrapperContext } from '@ice/mf-runtime';
+
+export function createMyPlugin(options = {}): EnhancedRuntimePlugin {
+  return {
+    name: 'my-plugin',
+    
+    wrapComponent: (WrappedComponent, context: WrapperContext) => {
+      // 🔑 使用上下文提供的 React 实例
+      const { React: ContextReact } = context;
+      
+      const MyWrapper = ContextReact.forwardRef<any, any>((props, ref) => {
+        ContextReact.useEffect(() => {
+          console.log(`Component ${context.remoteName}/${context.moduleName} mounted`);
+        }, []);
+        
+        return ContextReact.createElement(WrappedComponent, { ...props, ref });
+      });
+      
+      MyWrapper.displayName = `MyWrapper(${WrappedComponent.displayName || 'Component'})`;
+      return MyWrapper;
+    },
+    
+    injectProps: (props, context) => {
+      return {
+        ...props,
+        pluginData: 'injected by my plugin'
+      };
+    }
+  };
+}
+```
+
+## 内置插件示例
+
+### 日志记录插件
+
+```typescript
+import { 
+  createEnhancedLoggingPlugin,
+  developmentEnhancedLoggingPlugin,
+  productionEnhancedLoggingPlugin
+} from '@ice/mf-plugin-example';
+
+// 自定义配置
+registerEnhancedPlugins([createEnhancedLoggingPlugin({
+  level: 'info',
+  logComponentRender: true,
+  enablePerformanceMonitoring: true
+})]);
+
+// 或使用预定义插件
+registerEnhancedPlugins([
+  process.env.NODE_ENV === 'development' 
+    ? developmentEnhancedLoggingPlugin 
+    : productionEnhancedLoggingPlugin
+]);
+```
+
+### 属性注入插件
+
+```typescript
+import { createPropsInjectionPlugin } from '@ice/mf-plugin-example';
+
+registerEnhancedPlugins([createPropsInjectionPlugin({
+  globalProps: {
+    theme: 'dark',
+    version: '1.0.0'
+  }
+})]);
+```
+
+## 插件管理
+
+### 注册插件
+
+```typescript
+import { registerEnhancedPlugins } from '@ice/mf-runtime';
+
+// 注册多个插件（推荐方式）
+registerEnhancedPlugins([plugin1, plugin2, plugin3]);
+
+// 或通过插件管理器注册
+import { getEnhancedPluginManager } from '@ice/mf-runtime';
+const manager = getEnhancedPluginManager();
+manager.register(myPlugin);
+manager.registerPlugins([plugin1, plugin2]);
+```
+
+### 获取插件管理器
+
+```typescript
+import { getEnhancedPluginManager } from '@ice/mf-runtime';
+
+const manager = getEnhancedPluginManager();
+
+// 获取所有插件
+const plugins = manager.getPlugins();
+
+// 获取插件信息
+const info = manager.getPluginInfo();
+
+// 移除插件
+manager.removePlugin('plugin-name');
+
+// 清空所有插件
+manager.clear();
+```
+
+### 在组件中使用
+
+```typescript
+import { useEnhancedPluginManager } from '@ice/mf-runtime';
+
+function MyComponent() {
+  const pluginManager = useEnhancedPluginManager();
+  
+  // 动态注册插件
+  React.useEffect(() => {
+    pluginManager.register(createMyPlugin());
+  }, []);
+  
+  return <div>My Component</div>;
+}
+```
+
+## 远程组件配置
+
+### 基本配置
+
+```tsx
+<RemoteModule
+  scope="remote-app"
+  module="Button"
+  componentProps={{ text: 'Click me' }}
+/>
+```
+
+
+## 最佳实践
+
+### 1. React 实例一致性
+
+始终使用上下文提供的 React 实例，避免使用 JSX 语法：
+
+```typescript
+// ✅ 正确 - 使用上下文的 React 实例
+wrapComponent: (WrappedComponent, context) => {
+  const { React: ContextReact } = context;
+  return ContextReact.forwardRef((props, ref) => {
+    // 使用 createElement 确保实例一致性
+    return ContextReact.createElement(WrappedComponent, { ...props, ref });
+  });
+}
+
+// ❌ 错误 - 使用导入的 React 实例
+import React from 'react';
+wrapComponent: (WrappedComponent, context) => {
+  return React.forwardRef((props, ref) => {  // 可能是错误的 React 实例
+    return <WrappedComponent {...props} ref={ref} />; // JSX 使用编译时的 React
+  });
+}
+```
+
+**为什么不能直接用 JSX？**
+
+在微前端场景中：
+- 主应用和远程模块可能使用不同版本的 React
+- JSX 编译时绑定到特定的 React 实例
+- 使用 `ContextReact.createElement` 确保运行时使用正确的实例
+
+### 2. Ref 转发
+
+确保正确转发 ref：
+
+```typescript
+const MyWrapper = ContextReact.forwardRef<any, any>((props, ref) => {
+  return ContextReact.createElement(WrappedComponent, { ...props, ref });
+});
+```
+
+## 故障排除
+
+### 常见问题
+
+1. **插件不生效**
+   - 确保插件已正确注册
+   - 检查插件名称是否唯一
+   - 验证插件函数是否正确实现
+
+2. **React Hook 错误**
+   - 确保使用上下文提供的 React 实例
+   - 检查是否在条件语句中使用 Hook
+
+3. **Ref 转发失败**
+   - 确保使用 `React.forwardRef`
+   - 检查 ref 是否正确传递给底层组件
+
+4. **类型错误**
+   - 确保导入正确的类型定义
+   - 使用 `React.ComponentType<any>` 处理动态组件类型
+
+### 调试技巧
+
+```typescript
+// 启用调试日志
+registerEnhancedPlugin(createEnhancedLoggingPlugin({
+  level: 'debug',
+  logComponentRender: true
+}));
+
+// 检查插件状态
+const manager = getEnhancedPluginManager();
+console.log('Registered plugins:', manager.getPluginInfo());
+```

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@ice/mf-runtime",
-  "version": "1.0.3-beta.1",
+  "version": "1.0.3-beta.2",
   "description": "ice mf runtime",
   "files": [
     "esm",
     "es2017",
     "cjs",
-    "dist"
+    "dist",
+    "docs"
   ],
   "main": "esm/index.js",
   "module": "esm/index.js",