@dev-to/react-loader 0.1.0

package/README.md

@@ -0,0 +1,59 @@
+# @dev-to/react-loader
+
+在宿主页面中动态加载 **Vite Dev Server** 上的 React 组件，并保持 React Fast Refresh/HMR 能力。
+
+该包默认与 `@dev-to/react-plugin`（Vite 侧）配套使用。
+
+## 安装
+
+```bash
+pnpm add @dev-to/react-loader
+```
+
+## 前置条件（Vite 侧）
+
+确保你的 Vite 项目启用了 `@dev-to/react-plugin`：
+
+```ts
+import { devToReactPlugin } from '@dev-to/react-plugin'
+
+devToReactPlugin({ MyCard: 'src/MyCard.tsx' })
+```
+
+## 使用
+
+```tsx
+import { ReactLoader } from '@dev-to/react-loader'
+
+export function Demo() {
+  return (
+    <ReactLoader
+      origin="http://localhost:5173"
+      name="MyCard"
+      componentProps={{ title: 'Hello' }}
+    />
+  )
+}
+```
+
+### 直接 URL 模式
+
+如果你已经拿到完整入口 URL，也可以绕过内部解析：
+
+```tsx
+<ReactLoader url="http://localhost:5173/@fs/abs/path/to/MyCard.tsx" componentProps={{}} />
+```
+
+## 默认桥接端点
+
+- Contract：`/__dev_to_react__/contract.js`
+- Init：`/__dev_to_react__/init.js`
+
+这些端点常量由 `@dev-to/react-shared` 统一定义，保证与 `@dev-to/react-plugin` 保持一致。
+
+可通过 `contractEndpoint` 自定义 contract 路径；init 路径由 contract 返回值决定（未提供时回退到默认值）。
+
+## 导出内容
+
+- React 组件：`ReactLoader`
+- 底层能力：`loadBridgeContract` / `ensureBridgeInit` / `resolveReactEntry` / `resolveReactEntryForLoader`

package/dist/ReactLoader.d.ts

@@ -0,0 +1,80 @@
+import { type ReactNode } from 'react';
+import { type DevToReactBridgeContract } from '@dev-to/react-shared';
+/**
+ * --- DevTo React Bridge Protocol Types & Utils ---
+ */
+export declare const DEFAULT_CONTRACT_ENDPOINT: "/__dev_to_react__/contract.js";
+export declare const DEFAULT_INIT_ENDPOINT: "/__dev_to_react__/init.js";
+/** 加载远程 dev server 的桥接合约（无副作用） */
+export declare function loadBridgeContract(origin: string, contractEndpoint?: string): Promise<DevToReactBridgeContract>;
+/** 初始化远程 dev server 的 HMR/Refresh 运行时 */
+export declare function ensureBridgeInit(origin: string, contract: DevToReactBridgeContract): Promise<void>;
+/**
+ * --- Entry Resolution Logic (Core Engine) ---
+ */
+export interface ReactEntryResolutionResult {
+    success: true;
+    entryUrl: string;
+}
+export interface ReactEntryResolutionError {
+    success: false;
+    error: {
+        message: string;
+        type: 'COMPONENT_NOT_FOUND' | 'CONTRACT_LOAD_FAILED';
+        componentName?: string;
+        errorReason?: string;
+        setupGuide?: {
+            title: string;
+            steps: string[];
+        };
+    };
+}
+export type ReactEntryResolution = ReactEntryResolutionResult | ReactEntryResolutionError;
+/**
+ * Core engine: Resolve dev server entry URL for a given component name from contract.
+ * This is business-agnostic and only handles the matching logic.
+ */
+export declare function resolveReactEntry(origin: string, componentName: string, contractEndpoint?: string): Promise<ReactEntryResolution>;
+/**
+ * Engine helper for host/business layer:
+ * Resolve entry and convert failures into a loader-friendly error object.
+ */
+export declare function resolveReactEntryForLoader(origin: string, componentName: string, contractEndpoint?: string): Promise<{
+    success: true;
+    entryUrl: string;
+} | {
+    success: false;
+    loaderError: ReactLoaderError;
+}>;
+export interface ReactLoaderError {
+    message: string;
+    origin?: string;
+    componentName?: string;
+    type?: string;
+    errorReason?: string;
+    statusCode?: number | string;
+    setupGuide?: {
+        title: string;
+        steps: string[];
+    };
+}
+export interface ReactLoaderProps<P extends Record<string, unknown> = Record<string, unknown>> {
+    /** Dev server origin (e.g., http://localhost:5173). Required if url is not provided. */
+    origin?: string;
+    /** Component name to resolve. Required if url is not provided. */
+    name?: string;
+    /** Direct entry URL (bypass internal resolution) */
+    url?: string;
+    contractEndpoint?: string;
+    componentProps: P;
+    loading?: ReactNode;
+    /** @deprecated Resolution error is now handled internally via origin/name props */
+    externalError?: ReactLoaderError | null;
+    /** 内部预留：允许覆盖默认错误渲染 */
+    renderError?: (error: Error | ReactLoaderError) => ReactNode;
+}
+/**
+ * React 开发态 ESM 组件加载器（宿主内联复用）
+ */
+export declare function ReactLoader<P extends Record<string, unknown> = Record<string, unknown>>(props: ReactLoaderProps<P>): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=ReactLoader.d.ts.map

package/dist/ReactLoader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReactLoader.d.ts","sourceRoot":"","sources":["../src/ReactLoader.tsx"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { DEFAULT_CONTRACT_ENDPOINT, DEFAULT_INIT_ENDPOINT, ReactLoader, ensureBridgeInit, loadBridgeContract, resolveReactEntry, resolveReactEntryForLoader, } from './ReactLoader.js';
+export type { ReactEntryResolution, ReactEntryResolutionError, ReactEntryResolutionResult, ReactLoaderError, ReactLoaderProps, } from './ReactLoader.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,WAAW,EACX,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,0BAA0B,GAC3B,MAAM,kBAAkB,CAAA;AAEzB,YAAY,EACV,oBAAoB,EACpB,yBAAyB,EACzB,0BAA0B,EAC1B,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,kBAAkB,CAAA"}

package/dist/index.js

@@ -0,0 +1,860 @@
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { DEV_TO_REACT_BASE_PATH, DEV_TO_REACT_CONTRACT_PATH, DEV_TO_REACT_DEBUG_HTML_PATH, DEV_TO_REACT_INIT_PATH, DEV_TO_REACT_NAMESPACE } from "@dev-to/react-shared";
+function isRecord(value) {
+    return 'object' == typeof value && null !== value;
+}
+function unwrapDefault(value) {
+    if (!isRecord(value)) return value;
+    const defaultValue = value['default'];
+    return null != defaultValue ? defaultValue : value;
+}
+function toError(value) {
+    return value instanceof Error ? value : new Error(String(value));
+}
+function resolveRemoteRuntime(runtimeModule) {
+    const runtimeRecord = isRecord(runtimeModule) ? runtimeModule : {};
+    const reactCandidate = runtimeRecord['default'] ?? runtimeRecord['React'] ?? runtimeModule;
+    const domCandidate = runtimeRecord['ReactDOMClient'];
+    if (!isRecord(reactCandidate) || 'function' != typeof reactCandidate['createElement'] || !isRecord(domCandidate) || 'function' != typeof domCandidate['createRoot']) throw new Error('Invalid React runtime module from dev server.');
+    return {
+        React: reactCandidate,
+        ReactDOMClient: domCandidate
+    };
+}
+const DEFAULT_CONTRACT_ENDPOINT = DEV_TO_REACT_CONTRACT_PATH;
+const DEFAULT_INIT_ENDPOINT = DEV_TO_REACT_INIT_PATH;
+function resolveEndpointUrl(origin, endpoint) {
+    if (endpoint.startsWith('http://') || endpoint.startsWith('https://')) return endpoint;
+    if (endpoint.startsWith('/')) return `${origin}${endpoint}`;
+    return `${origin}/${endpoint}`;
+}
+function isBridgeContract(value) {
+    if (!isRecord(value)) return false;
+    const paths = value['paths'];
+    const events = value['events'];
+    if (!isRecord(paths) || 'string' != typeof paths['reactRuntime']) return false;
+    if (!isRecord(events) || 'string' != typeof events['fullReload']) return false;
+    return true;
+}
+function resolveContract(initModule) {
+    const moduleRecord = isRecord(initModule) ? initModule : {};
+    const contractCandidate = moduleRecord['DEV_TO_REACT_CONTRACT'] ?? moduleRecord['default'] ?? null;
+    if (!contractCandidate) throw new Error('Dev server contract not found. Please ensure `@dev-to/react-plugin` (devToReactPlugin) is enabled in the Vite dev server.');
+    if (!isBridgeContract(contractCandidate)) throw new Error('Invalid dev server contract.');
+    return contractCandidate;
+}
+const nativeImport = new Function('url', 'return import(url)');
+const contractCache = new Map();
+const initCache = new Map();
+async function loadBridgeContract(origin, contractEndpoint) {
+    const endpoint = contractEndpoint || DEFAULT_CONTRACT_ENDPOINT;
+    const initUrl = resolveEndpointUrl(origin, endpoint);
+    if (contractCache.has(initUrl)) return contractCache.get(initUrl);
+    const p = nativeImport(initUrl).then((m)=>resolveContract(m)).catch(async (e)=>{
+        contractCache.delete(initUrl);
+        const err = e instanceof Error ? e : new Error(String(e));
+        if (err.message.includes('Failed to fetch')) try {
+            const resp = await fetch(initUrl, {
+                method: 'HEAD'
+            }).catch(()=>null);
+            if (resp) err.statusCode = resp.status;
+        } catch  {}
+        throw err;
+    });
+    contractCache.set(initUrl, p);
+    return p;
+}
+async function ensureBridgeInit(origin, contract) {
+    const initPath = contract?.paths?.initClient || DEFAULT_INIT_ENDPOINT;
+    const initUrl = resolveEndpointUrl(origin, initPath);
+    if (initCache.has(initUrl)) return initCache.get(initUrl);
+    const p = nativeImport(initUrl).then(()=>void 0).catch((e)=>{
+        initCache.delete(initUrl);
+        throw e instanceof Error ? e : new Error(String(e));
+    });
+    initCache.set(initUrl, p);
+    return p;
+}
+async function resolveReactEntry(origin, componentName, contractEndpoint) {
+    try {
+        const contract = await loadBridgeContract(origin, contractEndpoint);
+        const dev = contract?.dev || {};
+        const componentMap = dev.componentMap || {};
+        const entry = componentMap[componentName] || componentMap['*'];
+        if (!entry) {
+            const errorMessage = `Component "${componentName}" not found in devComponentMap`;
+            const isWildcardMode = !!componentMap['*'];
+            const errorReason = isWildcardMode ? `The component "${componentName}" is not configured, and the wildcard fallback is also missing or invalid.` : `The component "${componentName}" is not configured in devComponentMap. Please add it to your Vite configuration.`;
+            return {
+                success: false,
+                error: {
+                    message: errorMessage,
+                    type: 'COMPONENT_NOT_FOUND',
+                    componentName,
+                    errorReason,
+                    setupGuide: {
+                        title: 'Setup Guide',
+                        steps: [
+                            "import { devToReactPlugin } from '@dev-to/react-plugin'",
+                            '',
+                            "// Option 1: Shorthand (Default)",
+                            `devToReactPlugin('${componentName}')`,
+                            '',
+                            "// Option 2: Explicit Mapping",
+                            "devToReactPlugin({",
+                            `  '${componentName}': '/', // Default entry`,
+                            "  'Other': 'src/Card.tsx' // Specific file",
+                            "})"
+                        ]
+                    }
+                }
+            };
+        }
+        const entryUrl = entry.startsWith('http://') || entry.startsWith('https://') ? entry : `${origin}${entry.startsWith('/') ? '' : '/'}${entry}`;
+        return {
+            success: true,
+            entryUrl
+        };
+    } catch (e) {
+        const errorMessage = e instanceof Error ? e.message : String(e);
+        return {
+            success: false,
+            error: {
+                message: errorMessage,
+                type: 'CONTRACT_LOAD_FAILED'
+            }
+        };
+    }
+}
+async function resolveReactEntryForLoader(origin, componentName, contractEndpoint) {
+    const r = await resolveReactEntry(origin, componentName, contractEndpoint);
+    if (r.success) return r;
+    const e = r.error;
+    return {
+        success: false,
+        loaderError: {
+            message: e.message,
+            origin,
+            componentName: e.componentName || componentName,
+            type: e.type,
+            errorReason: e.errorReason,
+            setupGuide: e.setupGuide
+        }
+    };
+}
+function safeLocationHref() {
+    if ("u" < typeof window) return '';
+    try {
+        return window.location.href;
+    } catch  {
+        return '';
+    }
+}
+function safeOrigin() {
+    if ("u" < typeof window) return '';
+    try {
+        return window.location.origin;
+    } catch  {
+        return '';
+    }
+}
+function getOriginFromFinalJsUrl(finalJsUrl) {
+    let origin = '';
+    try {
+        const urlParam = finalJsUrl.match(/url=([^&]+)/)?.[1] || '';
+        const decoded = urlParam ? decodeURIComponent(urlParam) : finalJsUrl;
+        const parsed = decoded.startsWith('http') ? new URL(decoded) : new URL(decoded, safeLocationHref() || 'http://localhost');
+        origin = parsed.origin;
+    } catch  {
+        origin = safeOrigin();
+    }
+    return origin;
+}
+function useReactLoader(options) {
+    const { url: directUrl, origin, name, componentProps, contractEndpoint } = options;
+    const containerRef = useRef(null);
+    const rootRef = useRef(null);
+    const runtimeRef = useRef(null);
+    const cardRef = useRef(null);
+    const fullReloadListenerRef = useRef(null);
+    const propsRef = useRef(componentProps);
+    propsRef.current = componentProps;
+    const [isReady, setIsReady] = useState(false);
+    const [error, setError] = useState(null);
+    const [version, setVersion] = useState(0);
+    const [resolvedUrl, setResolvedUrl] = useState(directUrl);
+    useEffect(()=>{
+        if (directUrl) {
+            setResolvedUrl(directUrl);
+            setError(null);
+            return;
+        }
+        if (!origin || !name) {
+            if (!directUrl && (origin || name)) setError(new Error('Missing dev server origin or component name for resolution.'));
+            return;
+        }
+        let cancelled = false;
+        setIsReady(false);
+        setError(null);
+        resolveReactEntryForLoader(origin, name, contractEndpoint).then((res)=>{
+            if (cancelled) return;
+            if (true === res.success) setResolvedUrl(res.entryUrl);
+            else setError(res.loaderError);
+        });
+        return ()=>{
+            cancelled = true;
+        };
+    }, [
+        directUrl,
+        origin,
+        name,
+        contractEndpoint
+    ]);
+    const ensureFullReloadListener = useCallback((eventName)=>{
+        if (!eventName) return;
+        if ("u" < typeof window) return;
+        const { current } = fullReloadListenerRef;
+        if (current?.eventName === eventName) return;
+        if (current) window.removeEventListener(current.eventName, current.handler);
+        const handler = ()=>{
+            setVersion((v)=>v + 1);
+        };
+        window.addEventListener(eventName, handler);
+        fullReloadListenerRef.current = {
+            eventName,
+            handler
+        };
+    }, []);
+    useEffect(()=>()=>{
+            if ("u" < typeof window) return;
+            const { current } = fullReloadListenerRef;
+            if (current) window.removeEventListener(current.eventName, current.handler);
+        }, []);
+    const renderViteRoot = useCallback(()=>{
+        const runtime = runtimeRef.current;
+        const Card = cardRef.current;
+        if (!runtime || !Card) return;
+        if (!containerRef.current) return;
+        if (!rootRef.current) rootRef.current = runtime.ReactDOMClient.createRoot(containerRef.current);
+        rootRef.current.render(runtime.React.createElement(Card, propsRef.current));
+    }, []);
+    const loadViteComponent = useCallback(async (entryUrl, exportName, currentVersion)=>{
+        if (!entryUrl) throw new Error('Not found entry url.');
+        const originFromUrl = getOriginFromFinalJsUrl(entryUrl);
+        const connector = entryUrl.includes('?') ? '&' : '?';
+        const jsUrlWithParam = currentVersion > 0 ? `${entryUrl}${connector}v=${currentVersion}` : entryUrl;
+        try {
+            const contract = await loadBridgeContract(originFromUrl, contractEndpoint);
+            await ensureBridgeInit(originFromUrl, contract);
+            ensureFullReloadListener(contract.events.fullReload);
+            const runtimeModule = await nativeImport(`${originFromUrl}${contract.paths.reactRuntime}`);
+            const runtime = resolveRemoteRuntime(runtimeModule);
+            const moduleNs = await nativeImport(jsUrlWithParam);
+            const moduleRecord = isRecord(moduleNs) ? moduleNs : {};
+            const exportCandidate = exportName ? moduleRecord[exportName] : void 0;
+            const candidate = exportName ? exportCandidate ?? moduleRecord['default'] ?? moduleNs : moduleRecord['default'] ?? moduleNs;
+            const Card = unwrapDefault(candidate);
+            if (Card) return {
+                Card: Card,
+                runtime
+            };
+            throw new Error('Vite Dev Component Load Fail: Component not found in module.');
+        } catch (e) {
+            const err = toError(e);
+            if (err.message.includes('Failed to fetch')) try {
+                const resp = await fetch(jsUrlWithParam, {
+                    method: 'HEAD'
+                }).catch(()=>null);
+                if (resp) err.statusCode = resp.status;
+            } catch  {}
+            throw err;
+        }
+    }, [
+        contractEndpoint,
+        ensureFullReloadListener
+    ]);
+    useEffect(()=>{
+        if (!resolvedUrl) return;
+        let cancelled = false;
+        setIsReady(false);
+        if (error instanceof Error) setError(null);
+        loadViteComponent(resolvedUrl, name, version).then(({ Card, runtime })=>{
+            if (cancelled) return;
+            runtimeRef.current = runtime;
+            cardRef.current = Card;
+            setIsReady(true);
+            renderViteRoot();
+        }).catch((err)=>{
+            if (cancelled) return;
+            setError(err instanceof Error ? err : new Error(String(err)));
+            setIsReady(false);
+        });
+        return ()=>{
+            cancelled = true;
+        };
+    }, [
+        loadViteComponent,
+        renderViteRoot,
+        resolvedUrl,
+        name,
+        version,
+        error
+    ]);
+    useEffect(()=>{
+        if (isReady) renderViteRoot();
+    });
+    useEffect(()=>()=>{
+            try {
+                rootRef.current?.unmount?.();
+            } catch  {}
+            rootRef.current = null;
+        }, []);
+    useEffect(()=>{
+        if (error) {
+            try {
+                rootRef.current?.unmount?.();
+            } catch  {}
+            rootRef.current = null;
+        }
+    }, [
+        error
+    ]);
+    return {
+        containerRef,
+        isReady,
+        error,
+        resolvedUrl
+    };
+}
+function InlineViteErrorView(props) {
+    const { errorMessage, currentOrigin, componentName, setupGuide, statusCode } = props;
+    const isComponentNotFound = errorMessage.includes('not found in devComponentMap');
+    const isFetchError = errorMessage.includes('Failed to fetch dynamically imported module');
+    const isInternalBridgeFile = errorMessage.includes(DEV_TO_REACT_BASE_PATH) || errorMessage.includes(DEV_TO_REACT_NAMESPACE);
+    const isContractError = errorMessage.includes('Vite dev contract not found') || errorMessage.includes('Failed to load Vite bridge contract') || errorMessage.includes('Failed to load contract from') || isFetchError && isInternalBridgeFile;
+    const isModuleFetchError = isFetchError && !isInternalBridgeFile;
+    let title = 'Vite Server Error';
+    let typeLabel = statusCode?.toString() || '500';
+    if (isComponentNotFound) {
+        title = 'Component Not Configured';
+        typeLabel = '412';
+    } else if (isModuleFetchError) {
+        title = 'Vite Module Not Found';
+        typeLabel = statusCode?.toString() || '404';
+    } else if (isContractError) {
+        title = 'Vite Server Connection Failed';
+        typeLabel = statusCode?.toString() || '503';
+    }
+    const theme = isContractError ? 'urgent' : 'warning';
+    const palette = 'urgent' === theme ? {
+        bg: 'linear-gradient(135deg, #fef2f2 0%, #fff5f5 100%)',
+        border: '#fecaca',
+        title: '#dc2626',
+        accent: '#dc2626',
+        pillBg: 'rgba(220, 38, 38, 0.05)',
+        pillBorder: 'rgba(220, 38, 38, 0.2)',
+        tipsBg: '#fffbeb',
+        tipsBorder: '#fde68a',
+        tipsText: '#92400e'
+    } : {
+        bg: 'linear-gradient(135deg, #fffbeb 0%, #fffdf2 100%)',
+        border: '#fde68a',
+        title: '#d97706',
+        accent: '#d97706',
+        pillBg: 'rgba(217, 119, 6, 0.05)',
+        pillBorder: 'rgba(217, 119, 6, 0.2)',
+        tipsBg: '#fffbeb',
+        tipsBorder: '#fde68a',
+        tipsText: '#92400e'
+    };
+    const styles = {
+        container: {
+            padding: 12,
+            borderRadius: 8,
+            background: palette.bg,
+            border: `1px solid ${palette.border}`,
+            boxShadow: '0 1px 4px rgba(0,0,0,0.06)'
+        },
+        header: {
+            display: 'flex',
+            alignItems: 'center',
+            gap: 8,
+            marginBottom: 10,
+            paddingBottom: 8,
+            borderBottom: `1px solid ${palette.border}66`
+        },
+        icon: {
+            fontSize: 18,
+            fontFamily: '"Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji", sans-serif'
+        },
+        title: {
+            fontSize: 12,
+            fontWeight: 700,
+            color: palette.title,
+            display: 'flex',
+            alignItems: 'center',
+            gap: 6
+        },
+        typeTag: {
+            fontSize: 11,
+            fontWeight: 700,
+            padding: '1px 6px',
+            borderRadius: 999,
+            border: `1px solid ${palette.pillBorder}`,
+            background: palette.pillBg,
+            color: palette.accent,
+            lineHeight: 1
+        },
+        content: {
+            display: 'flex',
+            flexDirection: 'column',
+            gap: 8
+        },
+        message: {
+            fontSize: 9,
+            color: '#991b1b',
+            background: '#fee2e2',
+            padding: 5,
+            borderRadius: 6,
+            borderLeft: `1px solid ${palette.accent}`,
+            whiteSpace: 'pre-wrap',
+            fontFamily: 'monospace',
+            wordBreak: 'break-word'
+        },
+        info: {
+            background: '#fff',
+            padding: '8px 10px',
+            borderRadius: 6,
+            border: `1px solid ${palette.border}`,
+            display: 'flex',
+            flexDirection: 'column',
+            gap: 6
+        },
+        infoRow: {
+            display: 'flex',
+            gap: 8,
+            alignItems: 'center'
+        },
+        label: {
+            fontSize: 11,
+            color: '#64748b',
+            fontWeight: 600,
+            width: 110,
+            textAlign: 'right'
+        },
+        value: {
+            fontSize: 11,
+            color: '#1e293b',
+            background: '#f8fafc',
+            padding: '3px 6px',
+            borderRadius: 4,
+            fontFamily: 'monospace',
+            border: '1px solid #e2e8f0',
+            wordBreak: 'break-word',
+            flex: 1
+        },
+        tips: {
+            background: palette.tipsBg,
+            padding: '8px 10px',
+            borderRadius: 6,
+            border: `1px solid ${palette.tipsBorder}`
+        },
+        tipsTitle: {
+            fontSize: 12,
+            fontWeight: 800,
+            color: palette.tipsText,
+            marginBottom: 6,
+            textAlign: 'center'
+        },
+        list: {
+            padding: 0,
+            listStyle: 'none',
+            display: 'flex',
+            flexDirection: 'column',
+            gap: 6
+        },
+        li: {
+            fontSize: 11,
+            color: '#78350f'
+        },
+        code: {
+            fontFamily: 'monospace',
+            fontSize: 10
+        },
+        link: {
+            color: '#2563eb'
+        },
+        codeBlock: {
+            padding: '10px 12px',
+            background: '#1e293b',
+            borderRadius: 6,
+            border: '1px solid #334155',
+            overflowX: 'auto',
+            fontSize: 11,
+            color: '#e2e8f0',
+            fontFamily: 'monospace'
+        },
+        codeComment: {
+            color: '#94a3b8',
+            fontStyle: 'italic'
+        }
+    };
+    const debugPanelUrl = `${currentOrigin}${DEV_TO_REACT_DEBUG_HTML_PATH}`;
+    const componentNameLabel = componentName || '';
+    return /*#__PURE__*/ jsxs("div", {
+        className: "vdev-container",
+        style: styles.container,
+        children: [
+            /*#__PURE__*/ jsxs("div", {
+                className: "vdev-header",
+                style: styles.header,
+                children: [
+                    /*#__PURE__*/ jsx("div", {
+                        className: "vdev-icon",
+                        style: styles.icon,
+                        children: '\u26A0\uFE0F'
+                    }),
+                    /*#__PURE__*/ jsxs("div", {
+                        className: "vdev-title",
+                        style: styles.title,
+                        children: [
+                            /*#__PURE__*/ jsx("span", {
+                                className: "vdev-type-tag",
+                                style: styles.typeTag,
+                                children: typeLabel
+                            }),
+                            title
+                        ]
+                    })
+                ]
+            }),
+            /*#__PURE__*/ jsxs("div", {
+                className: "vdev-content",
+                style: styles.content,
+                children: [
+                    /*#__PURE__*/ jsx("div", {
+                        className: "vdev-message",
+                        style: styles.message,
+                        children: errorMessage
+                    }),
+                    /*#__PURE__*/ jsxs("div", {
+                        className: "vdev-info",
+                        style: styles.info,
+                        children: [
+                            /*#__PURE__*/ jsxs("div", {
+                                className: "vdev-info-row",
+                                style: styles.infoRow,
+                                children: [
+                                    /*#__PURE__*/ jsx("span", {
+                                        className: "vdev-label",
+                                        style: styles.label,
+                                        children: "Server Address:"
+                                    }),
+                                    /*#__PURE__*/ jsx("code", {
+                                        className: "vdev-value",
+                                        style: styles.value,
+                                        children: currentOrigin
+                                    })
+                                ]
+                            }),
+                            componentNameLabel ? /*#__PURE__*/ jsxs("div", {
+                                className: "vdev-info-row",
+                                style: styles.infoRow,
+                                children: [
+                                    /*#__PURE__*/ jsx("span", {
+                                        className: "vdev-label",
+                                        style: styles.label,
+                                        children: "Component Name:"
+                                    }),
+                                    /*#__PURE__*/ jsx("code", {
+                                        className: "vdev-value",
+                                        style: styles.value,
+                                        children: componentNameLabel
+                                    })
+                                ]
+                            }) : null
+                        ]
+                    }),
+                    /*#__PURE__*/ jsxs("div", {
+                        className: "vdev-tips",
+                        style: styles.tips,
+                        children: [
+                            /*#__PURE__*/ jsx("div", {
+                                className: "vdev-tips-title",
+                                style: styles.tipsTitle,
+                                children: "Next Steps:"
+                            }),
+                            setupGuide ? /*#__PURE__*/ jsx("pre", {
+                                className: "vdev-code-block",
+                                style: styles.codeBlock,
+                                children: setupGuide.steps.map((step, idx)=>{
+                                    const stepKey = `step-${idx}`;
+                                    const commentIdx = step.indexOf('//');
+                                    if (-1 === commentIdx) return /*#__PURE__*/ jsx("div", {
+                                        children: step || ' '
+                                    }, stepKey);
+                                    const codePart = step.substring(0, commentIdx);
+                                    const commentPart = step.substring(commentIdx);
+                                    return /*#__PURE__*/ jsxs("div", {
+                                        children: [
+                                            /*#__PURE__*/ jsx("span", {
+                                                children: codePart
+                                            }),
+                                            /*#__PURE__*/ jsx("span", {
+                                                className: "vdev-code-comment",
+                                                style: styles.codeComment,
+                                                children: commentPart
+                                            })
+                                        ]
+                                    }, stepKey);
+                                })
+                            }) : /*#__PURE__*/ jsxs("ul", {
+                                className: "vdev-list",
+                                style: styles.list,
+                                children: [
+                                    isModuleFetchError ? /*#__PURE__*/ jsxs(Fragment, {
+                                        children: [
+                                            /*#__PURE__*/ jsxs("li", {
+                                                className: "vdev-li",
+                                                style: styles.li,
+                                                children: [
+                                                    /*#__PURE__*/ jsx("b", {
+                                                        children: "Verify Path"
+                                                    }),
+                                                    ": check the entry mapping for",
+                                                    ' ',
+                                                    /*#__PURE__*/ jsx("code", {
+                                                        className: "vdev-code",
+                                                        style: styles.code,
+                                                        children: componentNameLabel || 'this component'
+                                                    }),
+                                                    ' ',
+                                                    "in",
+                                                    ' ',
+                                                    /*#__PURE__*/ jsx("code", {
+                                                        className: "vdev-code",
+                                                        style: styles.code,
+                                                        children: "vite.config.ts"
+                                                    }),
+                                                    "."
+                                                ]
+                                            }),
+                                            /*#__PURE__*/ jsxs("li", {
+                                                className: "vdev-li",
+                                                style: styles.li,
+                                                children: [
+                                                    /*#__PURE__*/ jsx("b", {
+                                                        children: "Check Terminal"
+                                                    }),
+                                                    ": look at the terminal where",
+                                                    ' ',
+                                                    /*#__PURE__*/ jsx("code", {
+                                                        className: "vdev-code",
+                                                        style: styles.code,
+                                                        children: currentOrigin
+                                                    }),
+                                                    ' ',
+                                                    "is running for build errors."
+                                                ]
+                                            }),
+                                            /*#__PURE__*/ jsxs("li", {
+                                                className: "vdev-li",
+                                                style: styles.li,
+                                                children: [
+                                                    /*#__PURE__*/ jsx("b", {
+                                                        children: "Check Export"
+                                                    }),
+                                                    ": ensure the entry module exports a React component (default export recommended)."
+                                                ]
+                                            })
+                                        ]
+                                    }) : null,
+                                    isComponentNotFound ? /*#__PURE__*/ jsxs(Fragment, {
+                                        children: [
+                                            /*#__PURE__*/ jsxs("li", {
+                                                className: "vdev-li",
+                                                style: styles.li,
+                                                children: [
+                                                    /*#__PURE__*/ jsx("b", {
+                                                        children: "Update Config"
+                                                    }),
+                                                    ": map",
+                                                    ' ',
+                                                    /*#__PURE__*/ jsx("code", {
+                                                        className: "vdev-code",
+                                                        style: styles.code,
+                                                        children: componentNameLabel
+                                                    }),
+                                                    ' ',
+                                                    "in",
+                                                    ' ',
+                                                    /*#__PURE__*/ jsx("code", {
+                                                        className: "vdev-code",
+                                                        style: styles.code,
+                                                        children: "devComponentMap"
+                                                    }),
+                                                    "."
+                                                ]
+                                            }),
+                                            /*#__PURE__*/ jsxs("li", {
+                                                className: "vdev-li",
+                                                style: styles.li,
+                                                children: [
+                                                    /*#__PURE__*/ jsx("b", {
+                                                        children: "Wildcard Fallback"
+                                                    }),
+                                                    ": add",
+                                                    ' ',
+                                                    /*#__PURE__*/ jsx("code", {
+                                                        className: "vdev-code",
+                                                        style: styles.code,
+                                                        children: "'*': '/'"
+                                                    }),
+                                                    ' ',
+                                                    "to map all components to the default entry."
+                                                ]
+                                            })
+                                        ]
+                                    }) : null,
+                                    isContractError ? /*#__PURE__*/ jsxs(Fragment, {
+                                        children: [
+                                            /*#__PURE__*/ jsxs("li", {
+                                                className: "vdev-li",
+                                                style: styles.li,
+                                                children: [
+                                                    /*#__PURE__*/ jsx("b", {
+                                                        children: "Check Server"
+                                                    }),
+                                                    ": ensure your Vite server is running at",
+                                                    ' ',
+                                                    /*#__PURE__*/ jsx("code", {
+                                                        className: "vdev-code",
+                                                        style: styles.code,
+                                                        children: currentOrigin
+                                                    }),
+                                                    "."
+                                                ]
+                                            }),
+                                            /*#__PURE__*/ jsxs("li", {
+                                                className: "vdev-li",
+                                                style: styles.li,
+                                                children: [
+                                                    /*#__PURE__*/ jsx("b", {
+                                                        children: "Verify Origin"
+                                                    }),
+                                                    ": confirm localStorage key",
+                                                    ' ',
+                                                    /*#__PURE__*/ jsx("code", {
+                                                        className: "vdev-code",
+                                                        style: styles.code,
+                                                        children: "VITE_DEV_SERVER_ORIGIN"
+                                                    }),
+                                                    ' ',
+                                                    "is set to",
+                                                    ' ',
+                                                    /*#__PURE__*/ jsx("code", {
+                                                        className: "vdev-code",
+                                                        style: styles.code,
+                                                        children: currentOrigin
+                                                    }),
+                                                    "."
+                                                ]
+                                            }),
+                                            /*#__PURE__*/ jsxs("li", {
+                                                className: "vdev-li",
+                                                style: styles.li,
+                                                children: [
+                                                    /*#__PURE__*/ jsx("b", {
+                                                        children: "Open Debug Panel"
+                                                    }),
+                                                    ":",
+                                                    ' ',
+                                                    /*#__PURE__*/ jsx("a", {
+                                                        className: "vdev-link",
+                                                        style: styles.link,
+                                                        href: debugPanelUrl,
+                                                        target: "_blank",
+                                                        rel: "noreferrer",
+                                                        children: debugPanelUrl
+                                                    })
+                                                ]
+                                            })
+                                        ]
+                                    }) : null,
+                                    isModuleFetchError || isComponentNotFound || isContractError ? null : /*#__PURE__*/ jsxs("li", {
+                                        className: "vdev-li",
+                                        style: styles.li,
+                                        children: [
+                                            "Open Debug Panel:",
+                                            ' ',
+                                            /*#__PURE__*/ jsx("a", {
+                                                className: "vdev-link",
+                                                style: styles.link,
+                                                href: debugPanelUrl,
+                                                target: "_blank",
+                                                rel: "noreferrer",
+                                                children: debugPanelUrl
+                                            })
+                                        ]
+                                    })
+                                ]
+                            })
+                        ]
+                    })
+                ]
+            })
+        ]
+    });
+}
+function ReactLoader(props) {
+    const { url, origin, name, componentProps, contractEndpoint, loading, renderError, externalError } = props;
+    const state = useReactLoader({
+        url,
+        origin,
+        name,
+        componentProps,
+        contractEndpoint
+    });
+    const defaultLoading = /*#__PURE__*/ jsx("div", {
+        children: "Loading..."
+    });
+    const renderErrorNode = useCallback((err)=>{
+        if (renderError) return renderError(err);
+        const isLoaderErrorObject = !(err instanceof Error);
+        const errorMessage = err.message || String(err);
+        const currentOrigin = (isLoaderErrorObject ? err.origin : void 0) || origin || (url ? getOriginFromFinalJsUrl(url) : '');
+        const componentName = (isLoaderErrorObject ? err.componentName : void 0) || name;
+        const setupGuide = isLoaderErrorObject ? err.setupGuide : void 0;
+        const statusCode = isLoaderErrorObject ? err.statusCode : err.statusCode;
+        return /*#__PURE__*/ jsx(InlineViteErrorView, {
+            errorMessage: errorMessage,
+            currentOrigin: currentOrigin,
+            componentName: componentName,
+            setupGuide: setupGuide,
+            statusCode: statusCode
+        });
+    }, [
+        renderError,
+        name,
+        origin,
+        url
+    ]);
+    if (externalError) return /*#__PURE__*/ jsx(Fragment, {
+        children: renderErrorNode(externalError)
+    });
+    if (state.error) return /*#__PURE__*/ jsx(Fragment, {
+        children: renderErrorNode(state.error)
+    });
+    return /*#__PURE__*/ jsxs(Fragment, {
+        children: [
+            /*#__PURE__*/ jsx("div", {
+                ref: state.containerRef,
+                className: "vdev-loader-container",
+                "data-is": "ReactLoader"
+            }),
+            state.isReady ? null : loading ?? defaultLoading
+        ]
+    });
+}
+export { DEFAULT_CONTRACT_ENDPOINT, DEFAULT_INIT_ENDPOINT, ReactLoader, ensureBridgeInit, loadBridgeContract, resolveReactEntry, resolveReactEntryForLoader };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@dev-to/react-loader",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0",
+    "typescript": ">=5.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/YangYongAn/dev-to.git",
+    "directory": "packages/react-loader"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@dev-to/react-shared": "0.1.0"
+  },
+  "scripts": {
+    "build": "rslib build",
+    "dev": "rslib build --watch",
+    "lint": "pnpm -w lint",
+    "test": "echo 'test @dev-to/react-loader'"
+  }
+}