remote-reload-utils 0.0.8 → 0.0.11

package/CHANGELOG.md

@@ -0,0 +1,154 @@
+# Changelog
+
+所有重要的项目变更都将记录在此文件中。
+
+格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)，
+项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
+
+## [未发布]
+
+## [0.0.11] - 2026-03-16
+
+### Release
+
+- Published version 0.0.11 with patch bump
+
+
+## [0.0.10] - 2026-03-15
+
+### Release
+
+- Published version 0.0.10 with patch bump
+
+
+## [0.0.9] - 2026-03-15
+
+### Release
+
+- Published version 0.0.9 with patch bump
+
+
+### Refactor
+- 重构项目为模块化目录结构
+  - `src/loader/` - 核心加载模块
+  - `src/version/` - 版本管理模块
+  - `src/preload/` - 预加载模块
+  - `src/unload/` - 卸载管理模块
+  - `src/health/` - 健康检查模块
+  - `src/event-bus/` - 事件总线模块
+  - `src/plugins/` - 插件模块
+  - `src/types/` - 类型定义
+- 更新 rslib.config.ts entry 为 `./src/index.ts`
+- 更新 package.json types 路径为 `./dist/index.d.ts`
+
+### Changed
+- 修复 preloadRemote 引用从 loadRemote2 改为 loadRemote
+- 移除 App.tsx 中未使用的 React 导入
+- 添加 release 脚本到 package.json
+
+## [0.0.8] - 2026-03-15
+
+### Refactor
+- 抽离公共工具函数到 `loadRemoteUtils.ts`
+  - 新增 `fetchLatestVersion()` - 从 npm registry 获取最新版本
+  - 新增 `getVersionCache()` / `setVersionCache()` - 缓存管理
+  - 新增 `buildCdnUrls()` - 构建 CDN 地址列表
+  - 新增 `tryLoadRemote()` - 单个 URL 的加载重试逻辑
+  - 新增 `getFinalSharedConfig()` - 合并共享配置
+  - 新增 `resolveFinalVersion()` - 解析最终版本号
+  - 新增 `buildFinalUrls()` - 构建最终 URL 列表
+- 删除冗余文件 `loadRemote2.ts`
+- 简化 `loadRemote.ts`，使用公共工具函数
+
+### Changed
+- 更新 `index.ts` 导出，新增工具函数导出
+
+### Docs
+- 更新 `loadRemote.md`，添加工具函数 API 文档
+
+## [0.0.7] - 2026-03-15
+
+### Features
+- 新增微前端工具函数集
+  - 远程模块加载
+  - React 多版本支持
+  - 预加载功能
+  - 健康检查
+  - 事件总线
+
+## [0.0.6] - 2026-03-14
+
+### Docs
+- 更新 README 和 loadRemote.md 文档
+- 添加使用指南和 API 参考
+
+### Chore
+- 更新 remote-reload-utils 版本至 0.0.8
+
+## [0.0.5] - 2026-03-14
+
+### Features
+- 添加多版本远程加载功能
+- 支持自定义 shared 配置
+- 改进错误处理机制
+
+## [0.0.4] - 2026-03-14
+
+### Chore
+- 更新错误处理逻辑
+- 优化加载流程
+
+## [0.0.3] - 2026-03-14
+
+### Docs
+- 添加项目描述和 git 仓库信息
+- 更新 README 中的示例代码
+- 将 loadRemote.md 从 src 移动到根目录
+
+### Chore
+- 更新 remote-reload-utils 的版本号至 0.0.3
+
+## [0.0.2] - 2026-03-14
+
+### Features
+- 添加 React 多版本加载功能（v17/v18/v19）
+- 添加共享配置支持
+  - 默认共享 react 和 react-dom
+  - 支持自定义共享模块
+
+### Docs
+- 更新示例代码展示如何使用 loadRemoteMultiVersion
+
+## [0.0.1] - 2026-03-14
+
+### Features
+- 实现多版本远程模块加载功能
+  - 支持 CDN 故障转移（jsdelivr、unpkg）
+  - 支持本地 fallback 兜底
+  - 支持重试机制
+  - 支持版本缓存
+- 基础工具函数
+  - `loadRemoteMultiVersion()` - 加载远程模块
+  - `loadReactVersion()` - 加载特定版本 React
+
+---
+
+## 版本说明
+
+| 版本 | 日期 | 主要变更 |
+|------|------|----------|
+| 0.0.11 | 2026-03-16 | patch 版本发布 |
+|------|------|----------|
+| 0.0.10 | 2026-03-15 | patch 版本发布 |
+|------|------|----------|
+| 0.0.9 | 2026-03-15 | patch 版本发布 |
+|------|------|----------|
+| 0.0.9 | 2026-03-15 | 重构为模块化目录结构 |
+| 0.0.8 | 2026-03-15 | 重构代码结构，抽离公共工具函数 |
+| 0.0.7 | 2026-03-15 | 新增微前端工具函数集 |
+| 0.0.6 | 2026-03-14 | 文档更新 |
+| 0.0.5 | 2026-03-14 | 多版本远程加载 |
+| 0.0.4 | 2026-03-14 | 错误处理优化 |
+| 0.0.3 | 2026-03-14 | 文档和配置更新 |
+| 0.0.2 | 2026-03-14 | React 多版本支持 |
+| 0.0.1 | 2026-03-14 | 初始版本 |

package/README.md

@@ -24,6 +24,8 @@ pnpm dev
 
 ### 使用方式
 
+#### 1. 基础加载远程模块
+
 ```ts
 import { loadRemoteMultiVersion } from 'remote-reload-utils';
 const [comp, setComp] = useState(null);
@@ -52,3 +54,63 @@ useEffect(() => {
   init();
 }, []);
 ```
+
+#### 2. 使用 React 组件加载远程模块
+
+```tsx
+import { RemoteModuleCard, ErrorBoundary, lazyRemote } from 'remote-reload-utils';
+import React, { Suspense } from 'react';
+
+// 方式一：使用 RemoteModuleCard 组件（推荐）
+function App() {
+  return (
+    <RemoteModuleCard
+      pkg="@myorg/remote-app"
+      version="^1.0.0"
+      moduleName="Dashboard"
+      scopeName="myorg"
+      loadingFallback={<Spinner />}
+      errorFallback={(error, reset) => (
+        <div>
+          <p>加载失败：{error.message}</p>
+          <button onClick={reset}>重试</button>
+        </div>
+      )}
+      componentProps={{ userId: 123 }}
+    />
+  );
+}
+
+// 方式二：使用 lazy + Suspense
+const LazyDashboard = lazyRemote({
+  pkg: "@myorg/remote-app",
+  version: "^1.0.0",
+  moduleName: "Dashboard",
+  scopeName: "myorg"
+});
+
+function App() {
+  return (
+    <ErrorBoundary fallback={(error) => <div>错误：{error.message}</div>}>
+      <Suspense fallback={<Spinner />}>
+        <LazyDashboard userId={123} />
+      </Suspense>
+    </ErrorBoundary>
+  );
+}
+
+// 方式三：使用 SuspenseRemoteLoader（一体化方案）
+function App() {
+  return (
+    <SuspenseRemoteLoader
+      pkg="@myorg/remote-app"
+      version="^1.0.0"
+      moduleName="Dashboard"
+      scopeName="myorg"
+      fallback={<Spinner />}
+      errorFallback={(error) => <div>错误：{error.message}</div>}
+      componentProps={{ userId: 123 }}
+    />
+  );
+}
+```

package/dist/components/ErrorBoundary.d.ts

@@ -0,0 +1,34 @@
+import React from 'react';
+export interface ErrorBoundaryProps {
+    children: React.ReactNode;
+    fallback?: React.ReactNode | ((error: Error, resetError: () => void) => React.ReactNode);
+    onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
+    onReset?: () => void;
+}
+interface ErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+    errorInfo?: React.ErrorInfo | null;
+}
+/**
+ * 错误边界组件
+ * 用于捕获子组件树中的错误，并显示降级 UI
+ *
+ * @example
+ * ```tsx
+ * <ErrorBoundary
+ *   fallback={(error, reset) => <div onClick={reset}>Error: {error.message}</div>}
+ *   onError={(error, info) => console.error(error, info)}
+ * >
+ *   <MyComponent />
+ * </ErrorBoundary>
+ * ```
+ */
+export declare class ErrorBoundary extends React.Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    constructor(props: ErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): ErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void;
+    handleReset: () => void;
+    render(): string | number | boolean | Iterable<React.ReactNode> | import("react/jsx-runtime").JSX.Element | null | undefined;
+}
+export {};

package/dist/components/RemoteModuleCard.d.ts

@@ -0,0 +1,84 @@
+import React from 'react';
+import type { ErrorBoundaryProps } from './ErrorBoundary';
+export interface RemoteModuleCardProps {
+    /** 包名称 */
+    pkg: string;
+    /** 版本号，支持 semver 范围 */
+    version: string;
+    /** 远程模块名称（导出名） */
+    moduleName: string;
+    /** 作用域名称 */
+    scopeName: string;
+    /** 加载中的占位内容 */
+    loadingFallback?: React.ReactNode;
+    /** 错误状态的占位内容 */
+    errorFallback?: React.ReactNode | ((error: Error, resetError: () => void) => React.ReactNode);
+    /** 传递给远程组件的 props */
+    componentProps?: Record<string, any>;
+    /** 容器类名 */
+    className?: string;
+    /** 容器样式 */
+    style?: React.CSSProperties;
+    /** 加载成功回调 */
+    onLoad?: (component: React.ComponentType<any>) => void;
+    /** 加载失败回调 */
+    onError?: (error: Error) => void;
+    /** 是否禁用错误边界 */
+    disableErrorBoundary?: boolean;
+    /** 错误边界配置 */
+    errorBoundaryOptions?: Omit<ErrorBoundaryProps, 'children' | 'fallback'>;
+}
+interface ModuleState {
+    loading: boolean;
+    error: Error | null;
+    component: React.ComponentType<any> | null;
+}
+/**
+ * 内部 Hook：加载远程模块
+ */
+export declare function useRemoteModule({ pkg, version, moduleName, scopeName, onError, onLoad, }: RemoteModuleCardProps): ModuleState;
+/**
+ * 内部组件：纯内容渲染（不含 Suspense/ErrorBoundary）
+ */
+export declare function RemoteModuleCardContent({ pkg, version, moduleName, scopeName, loadingFallback, errorFallback, componentProps, className, style, onError, onLoad, }: RemoteModuleCardProps): import("react/jsx-runtime").JSX.Element | null;
+/**
+ * 远程模块卡片组件
+ * 负责加载和渲染远程模块，内置 Suspense 和 ErrorBoundary 支持
+ *
+ * @features
+ * - 自动加载远程模块
+ * - 内置加载状态和错误处理
+ * - 支持 Suspense 惰性加载
+ * - 可配置的错误边界
+ * - 支持重试机制
+ *
+ * @example
+ * ```tsx
+ * <RemoteModuleCard
+ *   pkg="@myorg/remote-app"
+ *   version="^1.0.0"
+ *   moduleName="Dashboard"
+ *   scopeName="myorg"
+ *   loadingFallback={<Spinner />}
+ *   errorFallback={(error, reset) => <Button onClick={reset}>Retry</Button>}
+ *   componentProps={{ userId: 123 }}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // 使用 lazy + Suspense 模式
+ * const LazyRemote = lazyRemote({
+ *   pkg: "@myorg/remote-app",
+ *   version: "^1.0.0",
+ *   moduleName: "Dashboard",
+ *   scopeName: "myorg"
+ * });
+ *
+ * <Suspense fallback={<Spinner />}>
+ *   <LazyRemote userId={123} />
+ * </Suspense>
+ * ```
+ */
+export declare function RemoteModuleCard(props: RemoteModuleCardProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/SuspenseLoader.d.ts

@@ -0,0 +1,131 @@
+import React, { type ComponentType, type ReactNode } from 'react';
+export interface LazyRemoteOptions {
+    /** 包名称 */
+    pkg: string;
+    /** 版本号 */
+    version?: string;
+    /** 模块名称 */
+    moduleName: string;
+    /** 作用域名称 */
+    scopeName: string;
+    /** 加载失败时的最大重试次数 */
+    maxRetries?: number;
+    /** 重试延迟（毫秒） */
+    retryDelay?: number;
+}
+export interface SuspenseRemoteProps {
+    /** 加载中的占位内容 */
+    fallback?: ReactNode;
+    children: ReactNode;
+}
+export interface SuspenseRemoteWithPropsProps extends LazyRemoteOptions {
+    /** 加载中的占位内容 */
+    fallback?: ReactNode;
+    /** 错误状态的占位内容 */
+    errorFallback?: ReactNode | ((error: Error) => ReactNode);
+    /** 传递给远程组件的 props */
+    componentProps?: Record<string, any>;
+}
+/**
+ * 创建一个惰性加载的远程组件
+ * 返回一个可用于 React.lazy() 的 Promise
+ *
+ * @example
+ * ```tsx
+ * const LazyDashboard = lazyRemote({
+ *   pkg: "@myorg/remote-app",
+ *   version: "^1.0.0",
+ *   moduleName: "Dashboard",
+ *   scopeName: "myorg"
+ * });
+ *
+ * function App() {
+ *   return (
+ *     <Suspense fallback={<Spinner />}>
+ *       <LazyDashboard userId={123} />
+ *     </Suspense>
+ *   );
+ * }
+ * ```
+ */
+export declare function lazyRemote(options: LazyRemoteOptions): React.LazyExoticComponent<React.ComponentType<any>>;
+/**
+ * 带 Suspense 和错误处理的远程组件包装器
+ * 注意：错误处理需要与 ErrorBoundary 配合使用
+ *
+ * @example
+ * ```tsx
+ * // 与 ErrorBoundary 配合使用
+ * <ErrorBoundary fallback={(error) => <div>Error: {error.message}</div>}>
+ *   <SuspenseRemote fallback={<Spinner />}>
+ *     <RemoteModuleCard pkg="@myorg/remote-app" version="^1.0.0" moduleName="Dashboard" scopeName="myorg" />
+ *   </SuspenseRemote>
+ * </ErrorBoundary>
+ * ```
+ */
+export declare function SuspenseRemote({ fallback, children, }: {
+    fallback?: ReactNode;
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * 一体化的远程组件加载器（包含 Suspense 和 ErrorBoundary）
+ *
+ * @example
+ * ```tsx
+ * <SuspenseRemoteLoader
+ *   pkg="@myorg/remote-app"
+ *   version="^1.0.0"
+ *   moduleName="Dashboard"
+ *   scopeName="myorg"
+ *   fallback={<Spinner />}
+ *   errorFallback={(error) => <div>Error: {error.message}</div>}
+ *   componentProps={{ userId: 123 }}
+ * />
+ * ```
+ */
+export declare function SuspenseRemoteLoader({ pkg, version, moduleName, scopeName, fallback, errorFallback, componentProps, }: SuspenseRemoteWithPropsProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * HOC：为组件添加远程加载能力
+ *
+ * @example
+ * ```tsx
+ * const EnhancedComponent = withRemote(
+ *   (props) => <div>{props.message}</div>,
+ *   {
+ *     pkg: "@myorg/remote-app",
+ *     version: "^1.0.0",
+ *     moduleName: "RemoteComponent",
+ *     scopeName: "myorg"
+ *   }
+ * );
+ *
+ * <EnhancedComponent message="Hello" />
+ * ```
+ */
+export declare function withRemote<P extends object>(WrappedComponent: ComponentType<P>, options: LazyRemoteOptions): (props: P) => import("react/jsx-runtime").JSX.Element;
+/**
+ * Hook：在函数组件中加载远程模块
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { component: RemoteComp, loading, error } = useRemoteModule({
+ *     pkg: "@myorg/remote-app",
+ *     version: "^1.0.0",
+ *     moduleName: "Dashboard",
+ *     scopeName: "myorg"
+ *   });
+ *
+ *   if (loading) return <Spinner />;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *   if (!RemoteComp) return null;
+ *
+ *   return <RemoteComp userId={123} />;
+ * }
+ * ```
+ */
+export declare function useRemoteModuleHook(options: LazyRemoteOptions): {
+    component: ComponentType<any> | null;
+    loading: boolean;
+    error: Error | null;
+};

package/dist/components/index.d.ts

@@ -0,0 +1,6 @@
+export { ErrorBoundary } from './ErrorBoundary';
+export type { ErrorBoundaryProps } from './ErrorBoundary';
+export { RemoteModuleCard } from './RemoteModuleCard';
+export type { RemoteModuleCardProps } from './RemoteModuleCard';
+export { lazyRemote, SuspenseRemote, SuspenseRemoteLoader, withRemote, useRemoteModuleHook, } from './SuspenseLoader';
+export type { LazyRemoteOptions, SuspenseRemoteProps, SuspenseRemoteWithPropsProps } from './SuspenseLoader';

package/dist/event-bus/index.d.ts

@@ -0,0 +1,40 @@
+type EventCallback<T = any> = (data: T, meta?: EventMeta) => void;
+interface EventMeta {
+    timestamp: number;
+    source?: string;
+    id?: string;
+}
+interface EventSubscription<T = any> {
+    callback: EventCallback<T>;
+    once: boolean;
+    filter?: (data: T, meta: EventMeta) => boolean;
+}
+interface EventEmitterOptions {
+    once?: boolean;
+    filter?: (data: any, meta: EventMeta) => boolean;
+}
+declare class EventBusClass {
+    private listeners;
+    private eventHistory;
+    private maxHistorySize;
+    private generateId;
+    on<T = any>(event: string, callback: EventCallback<T>, options?: EventEmitterOptions): () => void;
+    once<T = any>(event: string, callback: EventCallback<T>): () => void;
+    off<T = any>(event: string, callback?: EventCallback<T>): void;
+    emit<T = any>(event: string, data?: T, meta?: Partial<EventMeta>): void;
+    private addToHistory;
+    getHistory<T = any>(event: string): Array<{
+        data: T;
+        meta: EventMeta;
+    }>;
+    getEvents(): string[];
+    getListenerCount(event: string): number;
+    hasListeners(event: string): boolean;
+    clear(event?: string): void;
+    listenerExists(event: string, callback: EventCallback): boolean;
+    emitAsync<T = any>(event: string, data?: T, meta?: Partial<EventMeta>): Promise<void>;
+    static create(): EventBusClass;
+}
+export declare const eventBus: EventBusClass;
+export declare function createEventBus(): EventBusClass;
+export type { EventCallback, EventMeta, EventEmitterOptions, EventSubscription };

package/dist/health/index.d.ts

@@ -0,0 +1,23 @@
+import type { LoadRemoteOptions } from '../types';
+export interface HealthCheckResult {
+    pkg: string;
+    version: string;
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    latency: number;
+    cdn: string;
+    details: {
+        cdnReachable: boolean;
+        remoteEntryValid: boolean;
+        modulesLoadable: boolean;
+        error?: string;
+    };
+}
+export interface RemoteHealthReport {
+    timestamp: number;
+    overall: 'healthy' | 'degraded' | 'unhealthy';
+    remotes: HealthCheckResult[];
+}
+export declare function checkRemoteHealth(options: LoadRemoteOptions): Promise<HealthCheckResult>;
+export declare function checkModuleLoadable(scopeName: string, modulePath: string, mf: any): Promise<boolean>;
+export declare function getRemoteHealthReport(remotes: LoadRemoteOptions[]): Promise<RemoteHealthReport>;
+export declare function formatHealthStatus(status: 'healthy' | 'degraded' | 'unhealthy'): string;

package/dist/index.d.ts

@@ -1,2 +1,12 @@
-export { loadReactVersion } from './loadReactVersion';
-export { loadRemoteMultiVersion } from './loadRemote';
+export { loadReactVersion } from './version/react';
+export { checkVersionCompatibility, satisfiesVersion, findCompatibleVersion, getCompatibleReactVersions, fetchAvailableVersions, sortVersions, getLatestVersion, getStableVersions, extractMajorVersion, isPrerelease, compareVersions, parseVersion, } from './version';
+export { loadRemoteMultiVersion } from './loader';
+export { fetchLatestVersion, getVersionCache, setVersionCache, buildCdnUrls, tryLoadRemote, getFinalSharedConfig, resolveFinalVersion, buildFinalUrls, type LoadResult, } from './loader/utils';
+export { preloadRemote, preloadRemoteList, cancelPreload, clearPreloadCache, getPreloadStatus, } from './preload';
+export { unloadRemote, unloadAll, registerRemoteInstance, registerLoadedModule, getLoadedRemotes, isRemoteLoaded, } from './unload';
+export { checkRemoteHealth, checkModuleLoadable, getRemoteHealthReport, formatHealthStatus, } from './health';
+export { eventBus, createEventBus, } from './event-bus';
+export type { LoadRemoteOptions, VersionCache, PreloadOptions, PreloadCacheItem, PreloadStatus, } from './types';
+export { fallbackPlugin } from './plugins/fallback';
+export { ErrorBoundary, RemoteModuleCard, lazyRemote, SuspenseRemote, SuspenseRemoteLoader, withRemote, useRemoteModuleHook, } from './components';
+export type { ErrorBoundaryProps, RemoteModuleCardProps, LazyRemoteOptions, SuspenseRemoteProps, SuspenseRemoteWithPropsProps, } from './components';

package/dist/loader/index.d.ts

@@ -0,0 +1,6 @@
+import { ModuleFederationRuntimePlugin } from '@module-federation/enhanced/runtime';
+import type { LoadRemoteOptions } from '../types';
+/**
+ * 多版本共存的 loadRemote
+ */
+export declare function loadRemoteMultiVersion(options: LoadRemoteOptions, plugins: ModuleFederationRuntimePlugin[]): Promise<import("./utils").LoadResult>;

package/dist/loader/utils.d.ts

@@ -0,0 +1,38 @@
+import { createInstance, ModuleFederationRuntimePlugin } from '@module-federation/enhanced/runtime';
+import type { VersionCache } from '../types';
+/**
+ * 从 npm registry 获取最新版本，并增加类型安全性
+ */
+export declare function fetchLatestVersion(pkg: string): Promise<string>;
+/**
+ * 读取多版本缓存，增强健壮性
+ */
+export declare function getVersionCache(): VersionCache;
+/**
+ * 写入多版本缓存，增强健壮性
+ */
+export declare function setVersionCache(pkg: string, version: string): void;
+/**
+ * 拼接 CDN 地址 (统一使用抽象的模板)
+ */
+export declare function buildCdnUrls(pkg: string, version: string): string[];
+export interface LoadResult {
+    scopeName: string;
+    mf: ReturnType<typeof createInstance>;
+}
+/**
+ * 尝试加载单个远程模块 URL，包含重试逻辑
+ */
+export declare function tryLoadRemote(scopeName: string, url: string, retries: number, delay: number, sharedConfig: Record<string, any>, plugins: ModuleFederationRuntimePlugin[]): Promise<LoadResult>;
+/**
+ * 获取最终的共享配置
+ */
+export declare function getFinalSharedConfig(customShared?: Record<string, any>): Record<string, any>;
+/**
+ * 解析最终版本号（处理 latest 情况）
+ */
+export declare function resolveFinalVersion(pkg: string, version: string, cacheTTL: number, revalidate: boolean): Promise<string>;
+/**
+ * 构建最终的 URL 列表（包含本地 fallback）
+ */
+export declare function buildFinalUrls(pkg: string, version: string, localFallback?: string): string[];