如何在React/Vue/Svelte等项目中使用react-to-webcomponent转换的Web组件及解决依赖报错

问题根源 #

你遇到的错误核心原因是：当把react/react-dom放进dependencies后，Web组件包会把React代码打包进去。如果在React项目中使用这个Web组件，页面里会同时存在两个React实例——项目自身的React，以及Web组件包里的React。而React Hook（比如useRef）依赖单例的React内部上下文，多个实例会导致Hook无法找到正确的运行环境，最终抛出错误。

最优解决方案：双版本分发 #

通过配置打包工具，生成两个版本的组件包，分别适配React项目和非React项目：

1. 配置打包规则（以Vite为例） #

在vite.config.js中根据打包模式，区分是否将React设为外部依赖：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig(({ mode }) => {
  const isReactMode = mode === 'react'
  return {
    plugins: [react()],
    build: {
      lib: {
        entry: './src/web-component-wrapper.js', // 你的Web组件入口文件
        name: 'MyCustomWebComponent',
        fileName: (format) => `my-component.${format}.js`
      },
      rollupOptions: {
        // React模式下，将react/react-dom设为外部依赖，不打包进组件
        external: isReactMode ? ['react', 'react-dom'] : [],
        output: {
          globals: {
            react: 'React',
            'react-dom': 'ReactDOM'
          }
        }
      }
    }
  }
})

在package.json中添加两个打包命令：

{
  "scripts": {
    "build:react": "vite build --mode react",
    "build:standalone": "vite build --mode standalone"
  }
}

2. 配置包发布规则 #

在package.json中声明peerDependencies和多入口导出，让不同项目自动匹配对应版本：

{
  "peerDependencies": {
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  },
  "dependencies": {
    "react-to-webcomponent": "^1.1.0" // 仅保留必要的转换依赖
  },
  "exports": {
    ".": {
      "import": "./dist/my-component.es.js", // React项目默认导入此版本（不含React）
      "require": "./dist/my-component.umd.js"
    },
    "./standalone": "./dist/my-component.standalone.umd.js" // 非React项目导入此版本（包含React）
  }
}

3. 使用方式 #

• React项目：直接安装后导入组件，包会自动使用项目本身的React实例，避免冲突：

  import MyCustomWebComponent from 'your-package-name'
  // 或者直接用原React组件（更高效）
  import MyOriginalComponent from 'your-package-name/src/MyOriginalComponent'
  

• 非React项目（Vue/Svelte/原生JS）：引入独立打包版本，直接使用Web组件：

  <!-- 原生JS -->
  <script src="your-package-name/dist/my-component.standalone.umd.js"></script>
  <my-custom-web-component></my-custom-web-component>
  
  <!-- Vue项目 -->
  <template>
    <my-custom-web-component></my-custom-web-component>
  </template>
  <script>
    import 'your-package-name/standalone'
  </script>
  

简化备选方案：分两个包发布 #

如果不想配置复杂的打包规则，可以直接拆分两个独立包：

• 一个是原React组件包：将react/react-dom设为peerDependencies，仅供React项目使用
• 一个是Web组件独立包：打包时包含react/react-dom，发布为独立的umd包，供非React项目使用

内容的提问来源于stack exchange，提问作者Aditya Yaduvanshi