需要把任意组件封装成带 Shadow DOM 样式隔离…

用 isolet-js 将 React、Solid、Svelte 或 vanilla 组件打包为自包含、样式隔离、支持 script 标签嵌入的 drop-in Widget。

适用场景

解决思路

1. 安装依赖：运行 `npm install isolet-js`。
2. 从 `isolet-js` 导入 `createIsolet`，调用 `createIsolet({...})` 创建 widget；`name` 必填且唯一，`mount` 必填，签名为 `(container, props) => cleanup | void`。
3. 可选配置：`css` 传作用域 CSS；`isolation` 可选 `shadow-dom`、`scoped`、`none`；`shadowMode` 可选 `open`、`closed`；`hostAttributes` 设置宿主属性；`zIndex` 设置层级。
4. 挂载：调用 `widget.mount(document.body, { title: 'Hello' })` 把 widget 挂到目标容器并传 props。
5. 更新：调用 `widget.update({ title: 'Updated' })` 更新 props。
6. 卸载：调用 `widget.unmount()` 拆除 widget。
7. 读取实例属性：`widget.container` 是渲染容器 HTMLElement；`widget.shadowRoot` 是 ShadowRoot 或 null；`widget.mounted` 是布尔值。
8. React 适配：从 `isolet-js/react` 导入 `react`，在 `createIsolet` 中设置 `mount: react(Greeting)`，然后正常 `mount`、`update`、`unmount`。
9. Vanilla JS 适配：从 `isolet-js/vanilla` 导入 `vanilla`，设置 `mount: vanilla((container, props) => { ...; return cleanup; })`，在回调中把 DOM 追加到 `container`，并返回清理函数。
10. Solid 适配：在 `mount(container, props)` 中调用 `render(() => <App {...props} />, container)`，把返回的 `dispose` 作为清理函数返回。
11. Svelte 适配：在 `mount(container, props)` 中执行 `new App({ target: container, props })`，返回 `() => app.$destroy()` 作为清理函数。
12. 完整 CSS 隔离：设置 `isolation: 'shadow-dom'`（默认），在 shadow DOM 中渲染。
13. 作用域隔离：设置 `isolation: 'scoped'`，使用普通 div 包裹，样式全局注入。
14. 无隔离：设置 `isolation: 'none'`，直接挂载到目标元素。
15. CLI 初始化：运行 `npx isolet-js init` 生成 `isolet.config.ts`。
16. CLI 构建：运行 `npx isolet-js build` 根据配置打包 widget。
17. CLI 监听构建：运行 `npx isolet-js build --watch` 在文件变化时重新构建。
18. CLI 压缩构建：运行 `npx isolet-js build --minify` 生成压缩生产构建。
19. 配置文件：在 `isolet.config.ts` 中从 `isolet-js` 导入 `defineConfig`，导出 `defineConfig({ name, entry, styles, format: ['iife', 'esm'], outDir: './dist', globalName, external, dts: true, minify: true, platform: 'browser' })`；其中 `outDir` 默认 `dist`。
20. 多 widget 配置：导出数组，例如 `defineConfig([{ name: 'widget-a', entry: './src/a.ts', styles: './src/a.css' }, { name: 'widget-b', entry: './src/b.ts', format: ['esm'] }])`。
21. CSS/资产处理：配置中的 `styles` 会读取 CSS，把 `url()` 引用的字体/图片内联为 data URI，结果在入口中作为 `__ISOLET_CSS__` 可用。
22. CSS 导入：`.css` 导入会转换为 JS 字符串导出，适用于 shadow DOM。
23. 资产导入：`.png`、`.woff2`、`.mp3` 等资产导入会内联为 data URI。
24. createIsolet 的 styles 路径：在 `createIsolet` 中设置 `styles: './path.css'`，构建时会解析并内联。
25. 使用注入 CSS：在入口文件声明 `declare const __ISOLET_CSS__: string;`，然后在 `createIsolet` 中设置 `css: __ISOLET_CSS__`。
26. 或直接引用 CSS 路径：在 `createIsolet` 中设置 `styles: './widget.css'`，由 `isolet build` 解析。
27. 手动 Vite 插件：在 `vite.config.ts` 中从 `isolet-js/plugins` 导入 `cssTextPlugin`、`inlineAssetsPlugin`、`autoStylesPlugin`，并加入 `plugins` 数组。
28. Script 标签 IIFE 使用：添加 `<script src='https://unpkg.com/isolet-js/dist/index.iife.js'></script>`，从 `__ISOLET__` 解构 `createIsolet`，创建 widget 并 `mount`。
29. 打包自定义 widget 为 IIFE：配置 `format: ['iife']`、`globalName: 'MyWidget'`、`minify: true`，生成 `./dist/my-widget.iife.js`；HTML 中用 `MyWidget.widget.mount(document.getElementById('root'), { title: 'Hi' })` 挂载。
30. 按需懒挂载：创建 widget 后，在 `open-chat` 点击时如果 `!widget.mounted` 就 `widget.mount(document.body, { userId: currentUserId })`，在 `close-chat` 点击时 `widget.unmount()`。
31. z-index 覆盖层 widget：创建时设置 `zIndex: 10000` 和 `hostAttributes: { role: 'dialog', 'aria-modal': 'true' }`。
32. 响应式 props 更新：先 `widget.mount(document.body, { status: 'idle' })`，之后无需重新挂载，用 `widget.update({ status: 'loading' })`、`widget.update({ status: 'done' })` 更新。
33. 样式泄漏排查：使用 `isolation: 'shadow-dom'`（默认），并确认 `css` 选项或 `styles` 路径已正确设置；没有把 CSS 放进 shadow root 时宿主页面样式不会应用进去。
34. `__ISOLET_CSS__` undefined 排查：该变量只由 `isolet build` CLI 在配置了 `styles` 时注入；手动 Vite 构建要加入 `autoStylesPlugin()`。
35. 组件未渲染排查：确保 `mount` 函数把内容追加到 `container`，不要追加到 `document.body`；shadow DOM 模式下容器在 shadow root 内。
36. 清理未执行排查：从 `mount` 回调返回清理函数；否则 `widget.unmount()` 无法拆除框架内部资源（定时器、订阅等）。
37. IIFE 全局未找到排查：检查配置中的 `globalName` 与 HTML 引用一致；未设置 `globalName` 时运行时核心暴露 `globalThis.__ISOLET__`。
38. external 依赖运行时缺失排查：如果设置 `external: ['react']`，宿主页面必须在 widget 脚本加载前全局提供 `React`，或通过模块联邦提供。

适用边界 · 注意事项

• 无法引入 isolet-js、npm 依赖或构建流程的项目不适用。
• 宿主页面必须让自身 CSS 直接穿透进 widget 内部且不能调整 css/styles 配置时，默认 shadow-dom 隔离会阻断。
• 将依赖设为 external 但宿主页面无法在 widget 脚本加载前提供对应全局变量或模块联邦时不适用。