@melt-js/libs-utils

基于 hel-micro 的远程工具库，拆自上游模板 hel-eco/hel-tpl-remote-lib，并在本 pnpm workspace 中作为独立包维护。

| 项 | 值 | | --- | --- | | npm 包名 | @melt-js/libs-utils | | hel 组名（appGroupName / LIB_NAME） | libs-utils | | 本地联调地址 | http://localhost:10010 | | 构建 | Vite 5（UMD 单文件产物）+ rollup（hel_proxy） | | 单测 | Vitest |

来源与改造

上游模板是 CRA + webpack 4 的 hel 远程库模板，本包做了如下调整：

• 移除 React / CRA / webpack 4 相关配置与依赖：上游只把 CRA 当作调试页运行器，本包不需要 React。
• 构建改为 Vite 5：vite build 产出 hel_dist（UMD 单文件 + index.html），再由 hel-dev-utils 生成 hel-meta.json，最后由 rollup 产出 hel_proxy / hel_proxy_es。
• hel 依赖对齐 workspace 其他包并锁定精确版本：[email protected]、[email protected]、[email protected]。
• 单测从 jest 24 迁移到 Vitest（Node 22 下可直接运行）。
• npm 包名为 @melt-js/libs-utils，hel 组名（运行时标识）保持 libs-utils（与 @melt-js/comps-* 的处理方式一致，上游为 hel-tpl-remote-lib）。
• 工具函数保持上游语义（regs、num.canBeNum、num.random、myMod.sayHelloToHel），可直接替换使用。

目录说明

index.html                    调试页入口（Vite 的 html entry）
appInfo.mjs                   hel-dev-utils 子应用信息（homePage / distDir / externals）
vite.config.ts                base、UMD 单文件、10010 端口
rollup.config.js              产出 hel_proxy / hel_proxy_es
scripts/
  check.mjs                   校验 LIB_NAME 与 package.json 组名一致
  meta.mjs                    生成 hel_dist/hel-meta.json
  prepublishOnly.mjs          发布前校验版本号与 hel-meta.json 一致
src/
  index.ts                    入口：libReady 注册模块；master app 模式下加载调试页
  configs/subApp.ts           LIB_NAME，需与 package.json 的 appGroupName 一致
  entrance/libProperties.ts   暴露给使用方的工具集合
  entrance/libTypes.ts        类型入口 + rollup 打包入口（产出空壳代理）
  utils/                      regs / num / myMod
  loadApp.ts                  调试页（仅直接访问本工程时执行）

本地开发 / 构建 / 测试

# 在仓库根目录
pnpm libs-utils:dev            # 或在 libs-utils 目录 pnpm dev，起 10010
pnpm libs:test
pnpm libs:typecheck

# 构建
pnpm libs:build          # 发布用产物：资源地址指向 unpkg
pnpm libs:build:local    # 本地联调用产物：资源地址指向 http://localhost:10010

# 预览构建产物（先 build:local）
pnpm libs:build:local && pnpm libs:preview

要点：

• 端口固定 10010 且开启 strictPort：base 是绝对地址，端口漂移会导致宿主加载不到。
• base 由 appInfo.mjs 交给 hel-dev-utils 按环境推导：vite dev → http://localhost:10010/；vite build → https://unpkg.com/@melt-js/libs-utils@<version>/hel_dist/。需要覆盖时用 HEL_APP_HOME_PAGE（优先级最高，build:local 即基于此）。
• 直接访问 http://localhost:10010 可以看到调试页：src/index.ts 里 isMasterApp() 为 true 时才会 import('./loadApp')；作为远程库被宿主加载时不会执行。
• vite build 固定 format: 'umd' + inlineDynamicImports，与 hel 远程模块的“单入口、无代码分割”约定一致。

使用方接入

pnpm add @melt-js/libs-utils

预加载方式（推荐，在入口文件调用一次）：

import { preFetchLib } from 'hel-micro'

await preFetchLib('libs-utils')

// 默认导入拿到的是 Proxy，属性访问是实时的
import lib from '@melt-js/libs-utils'

lib.num.random(100)
lib.regs.en.test('abc')

请使用默认导入并访问 lib.xxx。hel_proxy 里的命名导出（regs / num / myMod）是在模块求值时解构的快照，只有在 preFetchLib 完成后才 import() 该包时才有效；顶部静态 import 会拿到 undefined。

懒加载方式：

const { num } = await preFetchLib('libs-utils')

本地联调时把 host 指向本工程的 dev server / preview：

await preFetchLib('libs-utils', {
  custom: { host: 'http://localhost:10010' },
})

类型：

import type { Lib } from '@melt-js/libs-utils'

产物与发布

pnpm build 产出：

• hel_dist/：vite build 的 UMD 产物 + hel-meta.json + index.html
• hel_proxy/、hel_proxy_es/：消费方 npm i @melt-js/libs-utils 后 import 到的空壳代理，真正实现由运行时 preFetchLib 注入

发布相关脚本：

• prepublishOnly：校验 package.json 版本号与 hel_dist/hel-meta.json 的 build_version 一致，且产物已构建。
• publish:stage：pnpm run build && npx -y npm@11 stage publish，走 npm stage 发布。

本包版本从 0.0.1 开始，与上游模板的 2.6.0 没有发布关系。