g3soft-frontend

G3Soft 前端技术基础设施：自研 Vue 3 组件库 + Docus 文档站，pnpm monorepo 管理。

目录结构

g3soft-frontend/
├── 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

启动文档站（默认 http://localhost:3000）。组件源码通过 alias 直连，改 packages/ui 会即时热更。

构建

pnpm gen:api      # 从组件源码重新生成 API 数据（改了 props/events/slots 后必跑）
pnpm build        # 构建 packages/*（组件库产出 dist）
pnpm build:docs   # 构建文档站静态文件

文档站静态产物在 docs/.output/public，可直接部署到任意静态托管。

部署到子路径

文档站支持挂载到子路径，构建时通过环境变量指定：

DOCS_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="<组件名>/<示例名>"} 引用。

3.2 KiB Raw Blame History Unescape Escape