g3soft-libs
G3Soft 技术基础设施：自研 Vue 3 组件库 + Docus 技术文档站（面向整体技术体系，不限于前端），pnpm monorepo 管理。
目录结构
g3soft-libs/
├── pnpm-workspace.yaml # workspace 声明 + catalog 统一版本 + 构建脚本白名单
├── packages/
│ ├── ui/ # 组件库（发布到 npm 私库）
│ │ ├── src/button/ # 一组件一目录
│ │ └── vite.config.ts # 产出 ESM + 类型声明
│ └── tokens/ # 设计变量，组件库与文档站共用
├── docs/ # 文档站（private，不发布）
│ ├── nuxt.config.ts # Docus Layer + alias 直连 packages 源码
│ ├── content/ # Markdown 内容（路由与导航自动生成）
│ ├── examples/ # 可运行示例，按组件分目录
│ ├── data/api/ # gen:api 生成的 API 数据（不要手改）
│ └── app/components/content # Demo.vue / ApiTable.vue（可在 md 中直接使用）
└── scripts/gen-api.mjs # 从组件源码生成 API 表格数据
环境要求
- Node.js >= 20.19
- pnpm 11（
better-sqlite3是 Docus 全文搜索依赖的原生模块，已在allowBuilds中放行）
安装
pnpm install
开发
pnpm dev
启动技术文档站：端口默认从 3000 起，被占用时自动向后选空闲端口（见 docs/scripts/dev.mjs）；控制台会打印本机（http://localhost:<port>）与局域网访问地址。组件源码通过 alias 直连，改 packages/ui 会即时热更。
构建
pnpm gen:api # 从组件源码重新生成 API 数据（改了 props/events/slots 后必跑）
pnpm build # 构建 packages/*（组件库产出 dist）
pnpm build:docs # 构建文档站静态文件
文档站静态产物在 docs/.output/public，可直接部署到任意静态托管。
部署到子路径
文档站支持挂载到子路径，构建时通过环境变量指定：
NUXT_APP_BASE_URL=/docs/ pnpm build:docs
发布组件包
组件库走 changesets 管理版本：
pnpm changeset # 记录本次改动
pnpm version # 生成版本号与 CHANGELOG
pnpm release # 构建并发布到私库
packages/ui 的 prepublishOnly 会执行 publint 校验包结构（exports、files 是否自洽）。
两条链路为什么互不干扰
| 文档站 | 组件包 | |
|---|---|---|
| 是否发布 | 否（private: true） |
是（npm 私库） |
| 版本管理 | 无 | changesets（已 ignore: ["@g3soft/docs"]） |
| 构建命令 | pnpm build:docs |
pnpm build |
| 产物 | docs/.output/public（静态） |
packages/ui/dist（ESM + d.ts） |
| 依赖边界 | Docus / Nuxt / Tailwind 只在 docs 包 |
只有 vue(peer) 与 @g3soft/tokens |
关键点：Nuxt 相关的依赖只出现在 docs/package.json，组件库的依赖树里没有任何文档站的东西；changesets 的 ignore 保证打 tag 发版时不会带上文档站。
约定
- 组件样式不写
scoped，用g3-前缀 + BEM，颜色尺寸一律引用--g3-*变量。 - API 表格由源码生成，禁止手写；改了组件记得跑
pnpm gen:api。 - 示例放
docs/examples/<组件名>/<示例名>.vue，在 md 中用::demo{name="<组件名>/<示例名>"}引用。