@dev-to/react-plugin 0.1.0

package/README.md

@@ -0,0 +1,64 @@
+# @dev-to/react-plugin
+
+一个用于 **Vite + React** 的“宿主桥接”插件：在 Vite Dev Server 上暴露稳定的桥接入口（contract/init/runtime/debug），让非 Vite 页面（例如 Electron、旧系统、微前端容器）也能加载并热更新 Vite 侧的 React 组件。
+
+## 安装
+
+```bash
+pnpm add -D @dev-to/react-plugin
+```
+
+## 使用
+
+在 `vite.config.ts` 中启用：
+
+```ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import { devToReactPlugin } from '@dev-to/react-plugin'
+
+export default defineConfig({
+  plugins: [
+    react(),
+    devToReactPlugin({
+      // 组件名 -> 入口路径（相对/绝对路径均可）
+      MyCard: 'src/MyCard.tsx',
+
+      // '/' 表示使用默认入口（优先 src/App.*，其次 src/index.*）
+      Other: '/'
+    })
+  ]
+})
+```
+
+### devComponentMap 形态
+
+- `devToReactPlugin()`：通配符模式（默认 `'*': '/'`），便于开发；但 `vite build --mode lib` 需要显式 componentName。
+- `devToReactPlugin('MyCard')`：字符串快捷模式，等价于 `{ MyCard: '/' }`。
+- `devToReactPlugin({ MyCard: 'src/MyCard.tsx' })`：显式映射（推荐，且 lib 构建必须）。
+
+## 稳定桥接路径
+
+插件会提供以下稳定路径（下划线版本）：
+
+- Contract：`/__dev_to_react__/contract.js`
+- Init（安装 HMR + React Refresh preamble）：`/__dev_to_react__/init.js`
+- React Runtime（React + ReactDOMClient）：`/__dev_to_react__/react-runtime.js`
+- Debug：`/__dev_to_react__/debug.html` / `debug.json`
+
+这些路径与事件名常量集中在 `@dev-to/react-shared`，用于保证 Vite 侧与宿主侧协议一致。
+
+## 生产构建（Library Mode）
+
+执行 `vite build --mode lib` 时，插件会按 `devComponentMap` 为每个组件产出一个 UMD bundle，默认输出到 `dist/<component>/`。
+
+> 提示：`'*': '/'` 的通配符模式仅适合开发；lib 构建请显式列出组件名。
+
+## 与 @dev-to/react-loader 配套
+
+宿主侧建议使用 `@dev-to/react-loader` 的 `ReactLoader`，它会自动：
+
+- 拉取 contract
+- 先加载 init（确保 Fast Refresh 生效）
+- 再加载 React Runtime 与目标模块
+- 监听 full-reload 事件并触发热重载

package/dist/constants.d.ts

@@ -0,0 +1,11 @@
+export declare const PLUGIN_NAME: "dev_to_react";
+export declare const PLUGIN_LOG_PREFIX: "[dev_to_react]";
+export declare const STABLE_BASE_PATH: "/__dev_to_react__";
+export declare const STABLE_CONTRACT_PATH: "/__dev_to_react__/contract.js";
+export declare const STABLE_INIT_PATH: "/__dev_to_react__/init.js";
+export declare const STABLE_REACT_RUNTIME_PATH: "/__dev_to_react__/react-runtime.js";
+export declare const STABLE_DEBUG_HTML_PATH: "/__dev_to_react__/debug.html";
+export declare const STABLE_DEBUG_JSON_PATH: "/__dev_to_react__/debug.json";
+export declare const EVENT_FULL_RELOAD: "dev_to_react:full-reload";
+export declare const EVENT_HMR_UPDATE: "dev_to_react:hmr-update";
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAYA,eAAO,MAAM,WAAW,gBAAyB,CAAA;AACjD,eAAO,MAAM,iBAAiB,kBAA8B,CAAA;AAE5D,eAAO,MAAM,gBAAgB,qBAAyB,CAAA;AACtD,eAAO,MAAM,oBAAoB,iCAA6B,CAAA;AAC9D,eAAO,MAAM,gBAAgB,6BAAyB,CAAA;AACtD,eAAO,MAAM,yBAAyB,sCAAkC,CAAA;AACxE,eAAO,MAAM,sBAAsB,gCAA+B,CAAA;AAClE,eAAO,MAAM,sBAAsB,gCAA+B,CAAA;AAElE,eAAO,MAAM,iBAAiB,4BAAiC,CAAA;AAC/D,eAAO,MAAM,gBAAgB,2BAAgC,CAAA"}

package/dist/debugHtml.d.ts

@@ -0,0 +1,20 @@
+import type { BridgeStats, DevComponentAudit } from './types.js';
+export interface ViteServerConfigLite {
+    host: unknown;
+    port?: number;
+    strictPort?: boolean;
+    cors?: unknown;
+    https: boolean;
+}
+export interface DebugHtmlRenderParams {
+    audit: DevComponentAudit;
+    resolvedDevComponentMap: Record<string, string>;
+    entryPathMap?: Record<string, string>;
+    stats: BridgeStats;
+    serverConfigLite: ViteServerConfigLite;
+    originCandidates: string[];
+    actualPort: number | undefined;
+    configFilePath?: string;
+}
+export declare function renderDebugHtml(params: DebugHtmlRenderParams): string;
+//# sourceMappingURL=debugHtml.d.ts.map

package/dist/debugHtml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debugHtml.d.ts","sourceRoot":"","sources":["../src/debugHtml.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEhE,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,OAAO,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,KAAK,EAAE,OAAO,CAAA;CACf;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,iBAAiB,CAAA;IACxB,uBAAuB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/C,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACrC,KAAK,EAAE,WAAW,CAAA;IAClB,gBAAgB,EAAE,oBAAoB,CAAA;IACtC,gBAAgB,EAAE,MAAM,EAAE,CAAA;IAC1B,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9B,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,qBAAqB,UAyf5D"}

package/dist/debugTools.d.ts

@@ -0,0 +1,10 @@
+import type { ViteDevServer } from 'vite';
+import type { BridgeContract, BridgeStats, DebugStartupState, DevComponentAudit } from './types.js';
+export interface DebugToolsContext {
+    contract: BridgeContract;
+    stats: BridgeStats;
+    audit: DevComponentAudit;
+    open?: boolean;
+}
+export declare function installDebugTools(server: ViteDevServer, ctx: DebugToolsContext, state: DebugStartupState): void;
+//# sourceMappingURL=debugTools.d.ts.map

package/dist/debugTools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debugTools.d.ts","sourceRoot":"","sources":["../src/debugTools.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,MAAM,CAAA;AAEzC,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEnG,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,cAAc,CAAA;IACxB,KAAK,EAAE,WAAW,CAAA;IAClB,KAAK,EAAE,iBAAiB,CAAA;IACxB,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAqFD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,EAAE,iBAAiB,EAAE,KAAK,EAAE,iBAAiB,QAkQxG"}

package/dist/devComponentMap.d.ts

@@ -0,0 +1,4 @@
+import type { DevComponentMapInput, ResolvedDevComponentConfig } from './types.js';
+export declare function toViteFsPath(filePath: string): string;
+export declare function resolveDevComponentConfig(rootDir: string, devComponentMap: DevComponentMapInput, fallbackRoot?: string): ResolvedDevComponentConfig;
+//# sourceMappingURL=devComponentMap.d.ts.map

package/dist/devComponentMap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"devComponentMap.d.ts","sourceRoot":"","sources":["../src/devComponentMap.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,oBAAoB,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAA;AAElF,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,UAI5C;AA4ED,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EACf,eAAe,EAAE,oBAAoB,EACrC,YAAY,CAAC,EAAE,MAAM,GACpB,0BAA0B,CAmE5B"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { EVENT_FULL_RELOAD, EVENT_HMR_UPDATE, PLUGIN_LOG_PREFIX, PLUGIN_NAME, STABLE_BASE_PATH, STABLE_CONTRACT_PATH, STABLE_DEBUG_HTML_PATH, STABLE_DEBUG_JSON_PATH, STABLE_INIT_PATH, STABLE_REACT_RUNTIME_PATH, } from './constants.js';
+export { devToReactPlugin, viteHostReactBridgePlugin } from './plugin.js';
+export type { BridgeContract, BridgeStats, BridgeStatsBucket, DebugStartupState, DevComponentAudit, DevComponentMapInput, DevToReactPluginOptions, ResolvedDevComponentConfig, ViteHostReactBridgePluginOptions, } from './types.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,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,EACX,gBAAgB,EAChB,oBAAoB,EACpB,sBAAsB,EACtB,sBAAsB,EACtB,gBAAgB,EAChB,yBAAyB,GAC1B,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EAAE,gBAAgB,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAA;AAEzE,YAAY,EACV,cAAc,EACd,WAAW,EACX,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,uBAAuB,EACvB,0BAA0B,EAC1B,gCAAgC,GACjC,MAAM,YAAY,CAAA"}