remote-reload-utils 0.0.10 → 0.0.11

package/CHANGELOG.md

@@ -7,6 +7,13 @@
 
 ## [未发布]
 
+## [0.0.11] - 2026-03-16
+
+### Release
+
+- Published version 0.0.11 with patch bump
+
+
 ## [0.0.10] - 2026-03-15
 
 ### Release
@@ -130,6 +137,8 @@
 
 | 版本 | 日期 | 主要变更 |
 |------|------|----------|
+| 0.0.11 | 2026-03-16 | patch 版本发布 |
+|------|------|----------|
 | 0.0.10 | 2026-03-15 | patch 版本发布 |
 |------|------|----------|
 | 0.0.9 | 2026-03-15 | patch 版本发布 |

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/index.d.ts

@@ -8,3 +8,5 @@ export { checkRemoteHealth, checkModuleLoadable, getRemoteHealthReport, formatHe
 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/main.cjs

@@ -1,5 +1,14 @@
 "use strict";
 var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.n = (module)=>{
+        var getter = module && module.__esModule ? ()=>module['default'] : ()=>module;
+        __webpack_require__.d(getter, {
+            a: getter
+        });
+        return getter;
+    };
+})();
 (()=>{
     __webpack_require__.d = (exports1, definition)=>{
         for(var key in definition)if (__webpack_require__.o(definition, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
@@ -27,31 +36,36 @@ __webpack_require__.d(__webpack_exports__, {
     compareVersions: ()=>compareVersions,
     fetchAvailableVersions: ()=>fetchAvailableVersions,
     sortVersions: ()=>sortVersions,
+    useRemoteModuleHook: ()=>useRemoteModuleHook,
     registerRemoteInstance: ()=>registerRemoteInstance,
     fallbackPlugin: ()=>fallbackPlugin,
     createEventBus: ()=>createEventBus,
+    withRemote: ()=>withRemote,
     getPreloadStatus: ()=>getPreloadStatus,
     parseVersion: ()=>parseVersion,
     resolveFinalVersion: ()=>resolveFinalVersion,
     buildFinalUrls: ()=>buildFinalUrls,
     fetchLatestVersion: ()=>fetchLatestVersion,
-    isRemoteLoaded: ()=>isRemoteLoaded,
+    ErrorBoundary: ()=>ErrorBoundary,
     getFinalSharedConfig: ()=>getFinalSharedConfig,
+    isRemoteLoaded: ()=>isRemoteLoaded,
     tryLoadRemote: ()=>tryLoadRemote,
     getVersionCache: ()=>getVersionCache,
     eventBus: ()=>eventBus,
     loadRemoteMultiVersion: ()=>loadRemoteMultiVersion,
     clearPreloadCache: ()=>clearPreloadCache,
-    loadReactVersion: ()=>loadReactVersion,
     getRemoteHealthReport: ()=>getRemoteHealthReport,
-    getStableVersions: ()=>getStableVersions,
     checkModuleLoadable: ()=>checkModuleLoadable,
-    buildCdnUrls: ()=>buildCdnUrls,
+    getStableVersions: ()=>getStableVersions,
     extractMajorVersion: ()=>extractMajorVersion,
+    buildCdnUrls: ()=>buildCdnUrls,
+    loadReactVersion: ()=>loadReactVersion,
     preloadRemoteList: ()=>preloadRemoteList,
+    SuspenseRemoteLoader: ()=>SuspenseRemoteLoader,
     registerLoadedModule: ()=>registerLoadedModule,
-    unloadRemote: ()=>unloadRemote,
     getCompatibleReactVersions: ()=>getCompatibleReactVersions,
+    SuspenseRemote: ()=>SuspenseRemote,
+    unloadRemote: ()=>unloadRemote,
     cancelPreload: ()=>cancelPreload,
     findCompatibleVersion: ()=>findCompatibleVersion,
     getLoadedRemotes: ()=>getLoadedRemotes,
@@ -59,10 +73,12 @@ __webpack_require__.d(__webpack_exports__, {
     preloadRemote: ()=>preloadRemote,
     satisfiesVersion: ()=>satisfiesVersion,
     formatHealthStatus: ()=>formatHealthStatus,
+    RemoteModuleCard: ()=>RemoteModuleCard,
     unloadAll: ()=>unloadAll,
     setVersionCache: ()=>setVersionCache,
-    isPrerelease: ()=>isPrerelease,
+    lazyRemote: ()=>lazyRemote,
     checkRemoteHealth: ()=>checkRemoteHealth,
+    isPrerelease: ()=>isPrerelease,
     checkVersionCompatibility: ()=>checkVersionCompatibility
 });
 const runtime_namespaceObject = require("@module-federation/enhanced/runtime");
@@ -751,6 +767,301 @@ const eventBus = EventBusClass.create();
 function createEventBus() {
     return EventBusClass.create();
 }
+const external_react_namespaceObject = require("react");
+var external_react_default = /*#__PURE__*/ __webpack_require__.n(external_react_namespaceObject);
+class ErrorBoundary extends external_react_default().Component {
+    constructor(props){
+        super(props);
+        this.state = {
+            hasError: false,
+            error: null,
+            errorInfo: null
+        };
+    }
+    static getDerivedStateFromError(error) {
+        return {
+            hasError: true,
+            error,
+            errorInfo: null
+        };
+    }
+    componentDidCatch(error, errorInfo) {
+        this.setState({
+            errorInfo
+        });
+        this.props.onError?.(error, errorInfo);
+        console.error('[RemoteReloadUtils] ErrorBoundary caught error:', error, errorInfo);
+    }
+    handleReset = ()=>{
+        this.setState({
+            hasError: false,
+            error: null,
+            errorInfo: null
+        });
+        this.props.onReset?.();
+    };
+    render() {
+        if (this.state.hasError && this.state.error) {
+            if ('function' == typeof this.props.fallback) return this.props.fallback(this.state.error, this.handleReset);
+            if (void 0 !== this.props.fallback) return this.props.fallback;
+            return /*#__PURE__*/ external_react_default().createElement("div", {
+                role: "alert",
+                style: {
+                    padding: '16px',
+                    border: '1px solid #ffcccc',
+                    backgroundColor: '#fff5f5',
+                    borderRadius: '4px'
+                }
+            }, /*#__PURE__*/ external_react_default().createElement("h3", null, "Something went wrong"), /*#__PURE__*/ external_react_default().createElement("p", null, this.state.error.message), /*#__PURE__*/ external_react_default().createElement("button", {
+                onClick: this.handleReset,
+                style: {
+                    marginTop: '8px',
+                    padding: '8px 16px',
+                    cursor: 'pointer'
+                }
+            }, "Try again"));
+        }
+        return this.props.children;
+    }
+}
+function useRemoteModule({ pkg, version, moduleName, scopeName, onError, onLoad }) {
+    const [moduleState, setModuleState] = (0, external_react_namespaceObject.useState)({
+        loading: true,
+        error: null,
+        component: null
+    });
+    (0, external_react_namespaceObject.useEffect)(()=>{
+        let mounted = true;
+        async function loadModule() {
+            try {
+                setModuleState((prev)=>({
+                        ...prev,
+                        loading: true,
+                        error: null
+                    }));
+                const { mf } = await loadRemoteMultiVersion({
+                    name: scopeName,
+                    pkg,
+                    version
+                }, []);
+                if (!mf || !mounted) return;
+                const mod = await mf.loadRemote(`${scopeName}/${moduleName}`);
+                if (!mounted) return;
+                if (mod && 'object' == typeof mod && 'default' in mod) {
+                    const Component = mod.default;
+                    setModuleState({
+                        loading: false,
+                        error: null,
+                        component: Component
+                    });
+                    onLoad?.(Component);
+                } else throw new Error(`Module "${scopeName}/${moduleName}" does not export a default component`);
+            } catch (err) {
+                if (mounted) {
+                    const error = err instanceof Error ? err : new Error(String(err));
+                    setModuleState({
+                        loading: false,
+                        error,
+                        component: null
+                    });
+                    onError?.(error);
+                }
+            }
+        }
+        loadModule();
+        return ()=>{
+            mounted = false;
+        };
+    }, [
+        pkg,
+        version,
+        moduleName,
+        scopeName,
+        onError,
+        onLoad
+    ]);
+    return moduleState;
+}
+function RemoteModuleCardContent({ pkg, version, moduleName, scopeName, loadingFallback, errorFallback, componentProps, className, style, onError, onLoad }) {
+    const moduleState = useRemoteModule({
+        pkg,
+        version,
+        moduleName,
+        scopeName,
+        onError,
+        onLoad
+    });
+    const [retryCount, setRetryCount] = (0, external_react_namespaceObject.useState)(0);
+    const handleRetry = (0, external_react_namespaceObject.useCallback)(()=>{
+        setRetryCount((prev)=>prev + 1);
+    }, []);
+    (0, external_react_namespaceObject.useEffect)(()=>{}, [
+        retryCount
+    ]);
+    if (moduleState.loading) return /*#__PURE__*/ external_react_default().createElement("div", {
+        className: className,
+        style: style,
+        role: "status",
+        "aria-live": "polite"
+    }, loadingFallback || /*#__PURE__*/ external_react_default().createElement("div", {
+        className: "module-card module-card--loading"
+    }, /*#__PURE__*/ external_react_default().createElement("div", {
+        className: "loading-spinner",
+        "aria-hidden": "true"
+    }), /*#__PURE__*/ external_react_default().createElement("span", null, "Loading ", moduleName, "...")));
+    if (moduleState.error) {
+        if ('function' == typeof errorFallback) return /*#__PURE__*/ external_react_default().createElement(external_react_default().Fragment, null, errorFallback(moduleState.error, handleRetry));
+        if (void 0 !== errorFallback) return /*#__PURE__*/ external_react_default().createElement(external_react_default().Fragment, null, errorFallback);
+        return /*#__PURE__*/ external_react_default().createElement("div", {
+            className: className,
+            style: style,
+            role: "alert"
+        }, /*#__PURE__*/ external_react_default().createElement("div", {
+            className: "module-card module-card--error"
+        }, /*#__PURE__*/ external_react_default().createElement("span", {
+            className: "error-icon",
+            "aria-hidden": "true"
+        }, "!"), /*#__PURE__*/ external_react_default().createElement("span", null, "Failed to load ", moduleName), /*#__PURE__*/ external_react_default().createElement("p", {
+            className: "error-message"
+        }, moduleState.error.message), /*#__PURE__*/ external_react_default().createElement("button", {
+            onClick: handleRetry,
+            className: "retry-button",
+            type: "button"
+        }, "Retry")));
+    }
+    if (!moduleState.component) return null;
+    const Component = moduleState.component;
+    return /*#__PURE__*/ external_react_default().createElement("div", {
+        className: className,
+        style: style
+    }, /*#__PURE__*/ external_react_default().createElement(Component, componentProps));
+}
+function RemoteModuleCard(props) {
+    const { disableErrorBoundary, errorFallback, loadingFallback, errorBoundaryOptions } = props;
+    if (disableErrorBoundary) return /*#__PURE__*/ external_react_default().createElement(external_react_namespaceObject.Suspense, {
+        fallback: loadingFallback || /*#__PURE__*/ external_react_default().createElement("div", null, "Loading...")
+    }, /*#__PURE__*/ external_react_default().createElement(RemoteModuleCardContent, props));
+    return /*#__PURE__*/ external_react_default().createElement(ErrorBoundary, {
+        fallback: errorFallback,
+        onError: errorBoundaryOptions?.onError,
+        onReset: errorBoundaryOptions?.onReset
+    }, /*#__PURE__*/ external_react_default().createElement(external_react_namespaceObject.Suspense, {
+        fallback: loadingFallback || /*#__PURE__*/ external_react_default().createElement("div", null, "Loading...")
+    }, /*#__PURE__*/ external_react_default().createElement(RemoteModuleCardContent, props)));
+}
+function lazyRemote(options) {
+    const { pkg, version = 'latest', moduleName, scopeName, maxRetries = 3, retryDelay = 1000 } = options;
+    let retryCount = 0;
+    const loadComponent = async ()=>{
+        try {
+            const { mf } = await loadRemoteMultiVersion({
+                name: scopeName,
+                pkg,
+                version
+            }, []);
+            if (!mf) throw new Error(`[RemoteReloadUtils] Failed to get Module Federation instance for ${scopeName}`);
+            const mod = await mf.loadRemote(`${scopeName}/${moduleName}`);
+            if (!mod || 'object' != typeof mod || !('default' in mod)) throw new Error(`[RemoteReloadUtils] Module "${scopeName}/${moduleName}" does not export a default component`);
+            return {
+                default: mod.default
+            };
+        } catch (error) {
+            if (retryCount < maxRetries) {
+                retryCount++;
+                await new Promise((resolve)=>setTimeout(resolve, retryDelay * retryCount));
+                return loadComponent();
+            }
+            throw error;
+        }
+    };
+    return /*#__PURE__*/ (0, external_react_namespaceObject.lazy)(loadComponent);
+}
+function SuspenseRemote({ fallback, children }) {
+    return /*#__PURE__*/ external_react_default().createElement(external_react_namespaceObject.Suspense, {
+        fallback: fallback || /*#__PURE__*/ external_react_default().createElement("div", null, "Loading...")
+    }, children);
+}
+function SuspenseRemoteLoader({ pkg, version = 'latest', moduleName, scopeName, fallback, errorFallback, componentProps }) {
+    const RemoteComponent = lazyRemote({
+        pkg,
+        version,
+        moduleName,
+        scopeName
+    });
+    if (errorFallback) return /*#__PURE__*/ external_react_default().createElement(ErrorBoundary, {
+        fallback: errorFallback
+    }, /*#__PURE__*/ external_react_default().createElement(external_react_namespaceObject.Suspense, {
+        fallback: fallback || /*#__PURE__*/ external_react_default().createElement("div", null, "Loading...")
+    }, /*#__PURE__*/ external_react_default().createElement(RemoteComponent, componentProps)));
+    return /*#__PURE__*/ external_react_default().createElement(external_react_namespaceObject.Suspense, {
+        fallback: fallback || /*#__PURE__*/ external_react_default().createElement("div", null, "Loading...")
+    }, /*#__PURE__*/ external_react_default().createElement(RemoteComponent, componentProps));
+}
+function withRemote(WrappedComponent, options) {
+    const RemoteComponent = lazyRemote(options);
+    return function(props) {
+        return /*#__PURE__*/ external_react_default().createElement(external_react_namespaceObject.Suspense, {
+            fallback: /*#__PURE__*/ external_react_default().createElement("div", null, "Loading...")
+        }, /*#__PURE__*/ external_react_default().createElement(RemoteComponent, props));
+    };
+}
+function useRemoteModuleHook(options) {
+    const { pkg, version = 'latest', moduleName, scopeName } = options;
+    const [state, setState] = (0, external_react_namespaceObject.useState)({
+        component: null,
+        loading: true,
+        error: null
+    });
+    (0, external_react_namespaceObject.useEffect)(()=>{
+        let mounted = true;
+        async function load() {
+            try {
+                setState((prev)=>({
+                        ...prev,
+                        loading: true,
+                        error: null
+                    }));
+                const { mf } = await loadRemoteMultiVersion({
+                    name: scopeName,
+                    pkg,
+                    version
+                }, []);
+                if (!mf) throw new Error(`[RemoteReloadUtils] Failed to get Module Federation instance for ${scopeName}`);
+                const mod = await mf.loadRemote(`${scopeName}/${moduleName}`);
+                if (mounted) if (mod && 'object' == typeof mod && 'default' in mod) setState({
+                    component: mod.default,
+                    loading: false,
+                    error: null
+                });
+                else throw new Error(`[RemoteReloadUtils] Module "${scopeName}/${moduleName}" does not export a default component`);
+            } catch (err) {
+                if (mounted) setState({
+                    component: null,
+                    loading: false,
+                    error: err instanceof Error ? err : new Error(String(err))
+                });
+            }
+        }
+        load();
+        return ()=>{
+            mounted = false;
+        };
+    }, [
+        pkg,
+        version,
+        moduleName,
+        scopeName
+    ]);
+    return {
+        component: state.component,
+        loading: state.loading,
+        error: state.error
+    };
+}
+exports.ErrorBoundary = __webpack_exports__.ErrorBoundary;
+exports.RemoteModuleCard = __webpack_exports__.RemoteModuleCard;
+exports.SuspenseRemote = __webpack_exports__.SuspenseRemote;
+exports.SuspenseRemoteLoader = __webpack_exports__.SuspenseRemoteLoader;
 exports.buildCdnUrls = __webpack_exports__.buildCdnUrls;
 exports.buildFinalUrls = __webpack_exports__.buildFinalUrls;
 exports.cancelPreload = __webpack_exports__.cancelPreload;
@@ -777,6 +1088,7 @@ exports.getStableVersions = __webpack_exports__.getStableVersions;
 exports.getVersionCache = __webpack_exports__.getVersionCache;
 exports.isPrerelease = __webpack_exports__.isPrerelease;
 exports.isRemoteLoaded = __webpack_exports__.isRemoteLoaded;
+exports.lazyRemote = __webpack_exports__.lazyRemote;
 exports.loadReactVersion = __webpack_exports__.loadReactVersion;
 exports.loadRemoteMultiVersion = __webpack_exports__.loadRemoteMultiVersion;
 exports.parseVersion = __webpack_exports__.parseVersion;
@@ -791,7 +1103,13 @@ exports.sortVersions = __webpack_exports__.sortVersions;
 exports.tryLoadRemote = __webpack_exports__.tryLoadRemote;
 exports.unloadAll = __webpack_exports__.unloadAll;
 exports.unloadRemote = __webpack_exports__.unloadRemote;
+exports.useRemoteModuleHook = __webpack_exports__.useRemoteModuleHook;
+exports.withRemote = __webpack_exports__.withRemote;
 for(var __webpack_i__ in __webpack_exports__)if (-1 === [
+    "ErrorBoundary",
+    "RemoteModuleCard",
+    "SuspenseRemote",
+    "SuspenseRemoteLoader",
     "buildCdnUrls",
     "buildFinalUrls",
     "cancelPreload",
@@ -818,6 +1136,7 @@ for(var __webpack_i__ in __webpack_exports__)if (-1 === [
     "getVersionCache",
     "isPrerelease",
     "isRemoteLoaded",
+    "lazyRemote",
     "loadReactVersion",
     "loadRemoteMultiVersion",
     "parseVersion",
@@ -831,7 +1150,9 @@ for(var __webpack_i__ in __webpack_exports__)if (-1 === [
     "sortVersions",
     "tryLoadRemote",
     "unloadAll",
-    "unloadRemote"
+    "unloadRemote",
+    "useRemoteModuleHook",
+    "withRemote"
 ].indexOf(__webpack_i__)) exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
 Object.defineProperty(exports, '__esModule', {
     value: true

package/dist/main.js

@@ -1,4 +1,5 @@
 import { createInstance } from "@module-federation/enhanced/runtime";
+import react, { Suspense, lazy, useCallback, useEffect, useState } from "react";
 async function loadReactVersion(version) {
     const runtime = await createInstance({
         name: `react_${version}_runtime`,
@@ -684,4 +685,293 @@ const eventBus = EventBusClass.create();
 function createEventBus() {
     return EventBusClass.create();
 }
-export { buildCdnUrls, buildFinalUrls, cancelPreload, checkModuleLoadable, checkRemoteHealth, checkVersionCompatibility, clearPreloadCache, compareVersions, createEventBus, eventBus, extractMajorVersion, fallbackPlugin, fetchAvailableVersions, fetchLatestVersion, findCompatibleVersion, formatHealthStatus, getCompatibleReactVersions, getFinalSharedConfig, getLatestVersion, getLoadedRemotes, getPreloadStatus, getRemoteHealthReport, getStableVersions, getVersionCache, isPrerelease, isRemoteLoaded, loadReactVersion, loadRemoteMultiVersion, parseVersion, preloadRemote, preloadRemoteList, registerLoadedModule, registerRemoteInstance, resolveFinalVersion, satisfiesVersion, setVersionCache, sortVersions, tryLoadRemote, unloadAll, unloadRemote };
+class ErrorBoundary extends react.Component {
+    constructor(props){
+        super(props);
+        this.state = {
+            hasError: false,
+            error: null,
+            errorInfo: null
+        };
+    }
+    static getDerivedStateFromError(error) {
+        return {
+            hasError: true,
+            error,
+            errorInfo: null
+        };
+    }
+    componentDidCatch(error, errorInfo) {
+        this.setState({
+            errorInfo
+        });
+        this.props.onError?.(error, errorInfo);
+        console.error('[RemoteReloadUtils] ErrorBoundary caught error:', error, errorInfo);
+    }
+    handleReset = ()=>{
+        this.setState({
+            hasError: false,
+            error: null,
+            errorInfo: null
+        });
+        this.props.onReset?.();
+    };
+    render() {
+        if (this.state.hasError && this.state.error) {
+            if ('function' == typeof this.props.fallback) return this.props.fallback(this.state.error, this.handleReset);
+            if (void 0 !== this.props.fallback) return this.props.fallback;
+            return /*#__PURE__*/ react.createElement("div", {
+                role: "alert",
+                style: {
+                    padding: '16px',
+                    border: '1px solid #ffcccc',
+                    backgroundColor: '#fff5f5',
+                    borderRadius: '4px'
+                }
+            }, /*#__PURE__*/ react.createElement("h3", null, "Something went wrong"), /*#__PURE__*/ react.createElement("p", null, this.state.error.message), /*#__PURE__*/ react.createElement("button", {
+                onClick: this.handleReset,
+                style: {
+                    marginTop: '8px',
+                    padding: '8px 16px',
+                    cursor: 'pointer'
+                }
+            }, "Try again"));
+        }
+        return this.props.children;
+    }
+}
+function useRemoteModule({ pkg, version, moduleName, scopeName, onError, onLoad }) {
+    const [moduleState, setModuleState] = useState({
+        loading: true,
+        error: null,
+        component: null
+    });
+    useEffect(()=>{
+        let mounted = true;
+        async function loadModule() {
+            try {
+                setModuleState((prev)=>({
+                        ...prev,
+                        loading: true,
+                        error: null
+                    }));
+                const { mf } = await loadRemoteMultiVersion({
+                    name: scopeName,
+                    pkg,
+                    version
+                }, []);
+                if (!mf || !mounted) return;
+                const mod = await mf.loadRemote(`${scopeName}/${moduleName}`);
+                if (!mounted) return;
+                if (mod && 'object' == typeof mod && 'default' in mod) {
+                    const Component = mod.default;
+                    setModuleState({
+                        loading: false,
+                        error: null,
+                        component: Component
+                    });
+                    onLoad?.(Component);
+                } else throw new Error(`Module "${scopeName}/${moduleName}" does not export a default component`);
+            } catch (err) {
+                if (mounted) {
+                    const error = err instanceof Error ? err : new Error(String(err));
+                    setModuleState({
+                        loading: false,
+                        error,
+                        component: null
+                    });
+                    onError?.(error);
+                }
+            }
+        }
+        loadModule();
+        return ()=>{
+            mounted = false;
+        };
+    }, [
+        pkg,
+        version,
+        moduleName,
+        scopeName,
+        onError,
+        onLoad
+    ]);
+    return moduleState;
+}
+function RemoteModuleCardContent({ pkg, version, moduleName, scopeName, loadingFallback, errorFallback, componentProps, className, style, onError, onLoad }) {
+    const moduleState = useRemoteModule({
+        pkg,
+        version,
+        moduleName,
+        scopeName,
+        onError,
+        onLoad
+    });
+    const [retryCount, setRetryCount] = useState(0);
+    const handleRetry = useCallback(()=>{
+        setRetryCount((prev)=>prev + 1);
+    }, []);
+    useEffect(()=>{}, [
+        retryCount
+    ]);
+    if (moduleState.loading) return /*#__PURE__*/ react.createElement("div", {
+        className: className,
+        style: style,
+        role: "status",
+        "aria-live": "polite"
+    }, loadingFallback || /*#__PURE__*/ react.createElement("div", {
+        className: "module-card module-card--loading"
+    }, /*#__PURE__*/ react.createElement("div", {
+        className: "loading-spinner",
+        "aria-hidden": "true"
+    }), /*#__PURE__*/ react.createElement("span", null, "Loading ", moduleName, "...")));
+    if (moduleState.error) {
+        if ('function' == typeof errorFallback) return /*#__PURE__*/ react.createElement(react.Fragment, null, errorFallback(moduleState.error, handleRetry));
+        if (void 0 !== errorFallback) return /*#__PURE__*/ react.createElement(react.Fragment, null, errorFallback);
+        return /*#__PURE__*/ react.createElement("div", {
+            className: className,
+            style: style,
+            role: "alert"
+        }, /*#__PURE__*/ react.createElement("div", {
+            className: "module-card module-card--error"
+        }, /*#__PURE__*/ react.createElement("span", {
+            className: "error-icon",
+            "aria-hidden": "true"
+        }, "!"), /*#__PURE__*/ react.createElement("span", null, "Failed to load ", moduleName), /*#__PURE__*/ react.createElement("p", {
+            className: "error-message"
+        }, moduleState.error.message), /*#__PURE__*/ react.createElement("button", {
+            onClick: handleRetry,
+            className: "retry-button",
+            type: "button"
+        }, "Retry")));
+    }
+    if (!moduleState.component) return null;
+    const Component = moduleState.component;
+    return /*#__PURE__*/ react.createElement("div", {
+        className: className,
+        style: style
+    }, /*#__PURE__*/ react.createElement(Component, componentProps));
+}
+function RemoteModuleCard(props) {
+    const { disableErrorBoundary, errorFallback, loadingFallback, errorBoundaryOptions } = props;
+    if (disableErrorBoundary) return /*#__PURE__*/ react.createElement(Suspense, {
+        fallback: loadingFallback || /*#__PURE__*/ react.createElement("div", null, "Loading...")
+    }, /*#__PURE__*/ react.createElement(RemoteModuleCardContent, props));
+    return /*#__PURE__*/ react.createElement(ErrorBoundary, {
+        fallback: errorFallback,
+        onError: errorBoundaryOptions?.onError,
+        onReset: errorBoundaryOptions?.onReset
+    }, /*#__PURE__*/ react.createElement(Suspense, {
+        fallback: loadingFallback || /*#__PURE__*/ react.createElement("div", null, "Loading...")
+    }, /*#__PURE__*/ react.createElement(RemoteModuleCardContent, props)));
+}
+function lazyRemote(options) {
+    const { pkg, version = 'latest', moduleName, scopeName, maxRetries = 3, retryDelay = 1000 } = options;
+    let retryCount = 0;
+    const loadComponent = async ()=>{
+        try {
+            const { mf } = await loadRemoteMultiVersion({
+                name: scopeName,
+                pkg,
+                version
+            }, []);
+            if (!mf) throw new Error(`[RemoteReloadUtils] Failed to get Module Federation instance for ${scopeName}`);
+            const mod = await mf.loadRemote(`${scopeName}/${moduleName}`);
+            if (!mod || 'object' != typeof mod || !('default' in mod)) throw new Error(`[RemoteReloadUtils] Module "${scopeName}/${moduleName}" does not export a default component`);
+            return {
+                default: mod.default
+            };
+        } catch (error) {
+            if (retryCount < maxRetries) {
+                retryCount++;
+                await new Promise((resolve)=>setTimeout(resolve, retryDelay * retryCount));
+                return loadComponent();
+            }
+            throw error;
+        }
+    };
+    return /*#__PURE__*/ lazy(loadComponent);
+}
+function SuspenseRemote({ fallback, children }) {
+    return /*#__PURE__*/ react.createElement(Suspense, {
+        fallback: fallback || /*#__PURE__*/ react.createElement("div", null, "Loading...")
+    }, children);
+}
+function SuspenseRemoteLoader({ pkg, version = 'latest', moduleName, scopeName, fallback, errorFallback, componentProps }) {
+    const RemoteComponent = lazyRemote({
+        pkg,
+        version,
+        moduleName,
+        scopeName
+    });
+    if (errorFallback) return /*#__PURE__*/ react.createElement(ErrorBoundary, {
+        fallback: errorFallback
+    }, /*#__PURE__*/ react.createElement(Suspense, {
+        fallback: fallback || /*#__PURE__*/ react.createElement("div", null, "Loading...")
+    }, /*#__PURE__*/ react.createElement(RemoteComponent, componentProps)));
+    return /*#__PURE__*/ react.createElement(Suspense, {
+        fallback: fallback || /*#__PURE__*/ react.createElement("div", null, "Loading...")
+    }, /*#__PURE__*/ react.createElement(RemoteComponent, componentProps));
+}
+function withRemote(WrappedComponent, options) {
+    const RemoteComponent = lazyRemote(options);
+    return function(props) {
+        return /*#__PURE__*/ react.createElement(Suspense, {
+            fallback: /*#__PURE__*/ react.createElement("div", null, "Loading...")
+        }, /*#__PURE__*/ react.createElement(RemoteComponent, props));
+    };
+}
+function useRemoteModuleHook(options) {
+    const { pkg, version = 'latest', moduleName, scopeName } = options;
+    const [state, setState] = useState({
+        component: null,
+        loading: true,
+        error: null
+    });
+    useEffect(()=>{
+        let mounted = true;
+        async function load() {
+            try {
+                setState((prev)=>({
+                        ...prev,
+                        loading: true,
+                        error: null
+                    }));
+                const { mf } = await loadRemoteMultiVersion({
+                    name: scopeName,
+                    pkg,
+                    version
+                }, []);
+                if (!mf) throw new Error(`[RemoteReloadUtils] Failed to get Module Federation instance for ${scopeName}`);
+                const mod = await mf.loadRemote(`${scopeName}/${moduleName}`);
+                if (mounted) if (mod && 'object' == typeof mod && 'default' in mod) setState({
+                    component: mod.default,
+                    loading: false,
+                    error: null
+                });
+                else throw new Error(`[RemoteReloadUtils] Module "${scopeName}/${moduleName}" does not export a default component`);
+            } catch (err) {
+                if (mounted) setState({
+                    component: null,
+                    loading: false,
+                    error: err instanceof Error ? err : new Error(String(err))
+                });
+            }
+        }
+        load();
+        return ()=>{
+            mounted = false;
+        };
+    }, [
+        pkg,
+        version,
+        moduleName,
+        scopeName
+    ]);
+    return {
+        component: state.component,
+        loading: state.loading,
+        error: state.error
+    };
+}
+export { ErrorBoundary, RemoteModuleCard, SuspenseRemote, SuspenseRemoteLoader, buildCdnUrls, buildFinalUrls, cancelPreload, checkModuleLoadable, checkRemoteHealth, checkVersionCompatibility, clearPreloadCache, compareVersions, createEventBus, eventBus, extractMajorVersion, fallbackPlugin, fetchAvailableVersions, fetchLatestVersion, findCompatibleVersion, formatHealthStatus, getCompatibleReactVersions, getFinalSharedConfig, getLatestVersion, getLoadedRemotes, getPreloadStatus, getRemoteHealthReport, getStableVersions, getVersionCache, isPrerelease, isRemoteLoaded, lazyRemote, loadReactVersion, loadRemoteMultiVersion, parseVersion, preloadRemote, preloadRemoteList, registerLoadedModule, registerRemoteInstance, resolveFinalVersion, satisfiesVersion, setVersionCache, sortVersions, tryLoadRemote, unloadAll, unloadRemote, useRemoteModuleHook, withRemote };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remote-reload-utils",
-  "version": "0.0.10",
+  "version": "0.0.11",
   "type": "module",
   "description": "Utilities for remote reload in Module Federation & React Component",
   "exports": {