imWebSdk — npm 发布与打包规范

本仓库用于将 utilsTs/ 目录下的 IM 通讯插件打包成 npm 包 pop-im-lib。仓库本身不会改动 utilsTs/ 下的源码，只负责：

• 通过 Vite 的库模式将源码打包成多种格式（标准版：ES/CJS/UMD；Bundle 版：单文件 UMD）；
• 将产物转译为 ES2015（兼容大多数依赖 ES5 语法的项目，例如 Nuxt2 + Vue2）；
• 只发布 dist/ 目录，以保证 npm 包体积可控。

构建输出

标准构建（不带依赖，适合 npm 安装）

运行 npm run build 后会得到以下文件：

| 文件 | 描述 | 典型用法 | | --- | --- | --- | | dist/popIM.es.js | ES Module | import YCIMLib from 'pop-im-lib' | | dist/popIM.cjs.js | CommonJS | const YCIMLib = require('pop-im-lib') | | dist/popIM.umd.js | UMD（挂载 window.YCIMLib） | 通过 <script> 加载，需要先引入依赖 | | dist/imSdk.d.ts | TypeScript 类型定义 | 自动提供类型提示 |

适合通过 npm 安装使用：

npm install pop-im-lib

// ES Module
import YCIMLib from 'pop-im-lib';

// CommonJS
const YCIMLib = require('pop-im-lib');

const sdk = YCIMLib.init('your-app-key');

注意：标准版本不包含第三方依赖，使用前需要确保项目中已安装以下依赖：

• axios
• dexie
• jszip
• mqtt
• node-forge
• protobufjs

Bundle 构建（包含所有依赖，适合 CDN 引入）

运行 npm run build:bundle 后会得到：

| 文件 | 描述 | 典型用法 | | --- | --- | --- | | dist/popIM.umd.bundle.js | UMD Bundle（包含所有依赖） | 直接通过 <script> 加载，无需引入其他依赖 |

推荐用于 CDN 直接引入：

<!-- 直接引入 Bundle 版本 -->
<script src="https://unpkg.com/pop-im-lib@latest/dist/popIM.umd.bundle.js"></script>
<script>
  // 直接使用，无需引入其他依赖
  const sdk = YCIMLib.init('your-app-key');
</script>

构建命令说明

• npm run build - 构建标准版本（ES/CJS/UMD，不带依赖，适合 npm 安装）
• npm run build:bundle - 构建 Bundle 版本（UMD，包含所有依赖，适合 CDN 引入）

所有产物都由 esbuild 按 target: 'es2015' 转译，避免 ?.、??、私有字段等语法给旧版 Webpack 带来解析错误。如果业务需要 ES5 runtime polyfill（如 Promise、Map），请在宿主项目自行注入。

目录结构

• utilsTs/：IM 插件源码；请在这里持续迭代业务逻辑。
• vite.config.js：仅负责打包配置（入口、外链依赖、输出格式与 ES2015 兼容设置）。
• dist/：构建产物；发布前通过 npm run build 或 npm run build:bundle 自动生成。

发布流程

1. 安装依赖

   npm install

2. 构建

   # 构建标准版本（ES/CJS/UMD，不带依赖）
   npm run build
      
   # 或构建 Bundle 版本（UMD，包含所有依赖）
   npm run build:bundle
      
   # 建议发布前同时构建两个版本
   npm run build && npm run build:bundle

3. 版本管理

   使用 semver 规范更新版本号：

   npm version patch -m "release: %s"

4. 发布到 npm

   npm publish --access public

5. 验证

   npm pack --dry-run
   npx envinfo --system --browsers

   或在干净目录中执行：

   npm install pop-im-lib
   node -e "console.log(Object.keys(require('pop-im-lib')))"

以上规范足以覆盖日常发布流程。如需在 utilsTs/ 中新增特性，只需重新运行构建命令并按上述步骤发布即可。