@vhst/hst-ui

基于 Element Plus 二次封装的 Vue 3 组件库。

特性

• 🪶 轻量封装 — 在 Element Plus 之上增加品牌主题与稳定 API。
• 🎨 主题可定制 — 暴露 SCSS 变量，按需覆盖品牌色。
• 🌲 按需引入 — ES Module + Tree-shaking，发布产物覆盖 ES/CJS/UMD。
• 🧪 TypeScript — 全部组件提供完整类型定义。

安装

pnpm add @vhst/hst-ui element-plus
# 或
npm install @vhst/hst-ui element-plus

快速上手

// main.ts
import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import '@vhst/hst-ui/dist/style.css'

import HstUI from '@vhst/hst-ui'
import App from './App.vue'

createApp(App).use(ElementPlus).use(HstUI).mount('#app')

按需引入：

<script setup lang="ts">
import { HstButton } from '@vhst/hst-ui'
</script>

<template>
  <hst-button type="primary">Primary</hst-button>
</template>

目录

| 路径 | 说明 | | ---- | ---- | | src/ | 组件源码 | | examples/ | 本地调试 playground | | docs/ | VitePress 文档 |

本地开发

pnpm install
pnpm dev          # 启动 examples playground
pnpm dev:docs     # 启动文档站
pnpm build        # 构建组件库产物到 dist/

发布

pnpm build
npm publish --access public
把包发布到 npm registry，并设置访问权限为 public（公开）。

具体细节：

1. npm publish — 把当前目录的包发布到 npm
2. --access public — 覆盖默认的访问限制

关键点：只有 scoped 包（名字带 @xxx/，比如 @yourname/utils）需要这个 flag。

  - 不带这个 flag 时，scoped 包默认是 restricted（私有），需要付费 npm org 账号才能发布
  - 加 --access public 后，scoped 包就当成公开免费包发布
  - 非 scoped 包（比如 react、lodash）本来就是 public，这个 flag 加不加没区别

常见报错对照：

  没加 --access public 发 scoped 包 → npm 报 402 Payment Required
  加上之后就能正常公开发布

也可以在 package.json 里永久写死，避免每次敲命令：

  "publishConfig": {
    "access": "public"
  }

这是 scoped 包发布到公网最常见的姿势。

发布 npm 包需要配置 / 准备的东西，按层次分：

    1. 账号与登录
       - 在 https://www.npmjs.com/ 注册账号，邮箱必须验证（没验证不能 publish）
       - 终端执行 npm login，输入 username / password / email / OTP（开了 2FA 的话）
       - 验证登录：npm whoami 应该返回你的用户名
       - CI/CD 场景：去 npm 网站生成 Automation Token 或 Granular Access Token，写进 ~/.npmrc 的 //registry.npmjs.org/:_authToken=...，不要用密码

    2. package.json 必填字段
       - name：包名，全局唯一；想用自己的命名空间就写 @你的用户名/包名（scoped）
       - version：semver，三段 x.y.z，每次 publish 必须比上次大
       - main / exports：入口文件
       - description、author、license、repository、keywords：可选但强烈建议填，搜索和可信度都靠它们
       - files：白名单，指定哪些文件被打进 tarball（不写就默认全部，但通常配合 .npmignore 排除 src、tests、.git 等）

    3. Registry 配置
       - 默认就是官方源 https://registry.npmjs.org/，一般不用改
       - 国内机器不翻墙经常 timeout，可以在 publish 时临时切源：npm publish --registry=https://registry.npmjs.org/（publish 只能走官方源，不能用 npmmirror）
       - 想看当前源：npm config get registry

    4. Scoped 包的小坑
       - @user/pkg 默认 private，要公开发布必须加 --access public：
         npm publish --access public
       - 包名在官方源上没被占用才能 unscoped 发布

    5. 2FA
       - 强烈建议开：npm profile enable-2fa auth-and-writes
       - 开之后每次 publish 都要输 OTP；如果嫌烦只开 auth-only（登录要 OTP，发布不要）
       （npm login 后在终端执行）

    6. 常用 .npmrc 片段（可选）
       - 用户级 ~/.npmrc：

         registry=https://registry.npmjs.org/
         //registry.npmjs.org/:_authToken=npm_xxxxxxxxxxxx
         save-exact=true

       - 项目级 .npmrc 同样格式，优先级更高

    发布流程的最小动作链：
    1. npm login 一次
    2. 写好 package.json，bump version
    3. npm pack 看一下会打进 tarball 的文件清单
    4. npm publish（scoped 包加 --access public）
    5. 报错先看：npm logout && npm login、检查版本号、检查包名冲突、检查邮箱验证

c:\Users\apple\Desktop\npm\
├── src/
│   ├── index.ts                          # 包入口 (Plugin + 默认导出)
│   ├── components/
│   │   ├── index.ts
│   │   └── Button/
│   │       ├── Button.vue                # 包装 <el-button>
│   │       ├── index.ts                  # 暴露 HstButton + install
│   │       └── types.ts                  # 公共类型
│   └── styles/
│       ├── variables.scss                # 主题变量 (可被消费者 @use 覆盖)
│       ├── button.scss                   # HST 品牌 BEM 微调
│       └── index.scss
├── examples/                             # 本地调试 playground
│   ├── index.html
│   ├── vite.config.ts
│   └── src/{main.ts,App.vue}
├── docs/                                 # VitePress 文档
│   ├── .vitepress/config.ts
│   ├── index.md
│   ├── guide/{index.md,quickstart.md}
│   └── components/button.md
├── scripts/copy-styles.mjs               # 构建后拷贝 SCSS 到 dist
├── package.json                          # @vhst/hst-ui, publishConfig.access=public
├── tsconfig.json
├── vite.config.ts                        # examples 配置
├── vite.config.lib.ts                    # 库构建 (ES+CJS+UMD+d.ts)
├── README.md / CHANGELOG.md / LICENSE
└── dist/                                 # 已生成的构建产物

License

MIT