create-vue-workspace

create-vue-workspace

一个可发布到 npm 的 CLI，用于生成 Vue 3 + Vite + TypeScript 的 pnpm monorepo 工作区，并以 Angular CLI 风格的 new + generate 命令持续生成代码。

命令别名：cvw（对应 create-vue-workspace）

命令模型

对齐 Angular CLI 的两段式：new 建工作区，generate 跑生成器。

cvw new [name]                  # 创建工作区
cvw generate <type> [name]      # 运行生成器，别名 cvw g
cvw update                      # 更新 cvw 自身到最新版本

生成器

所有生成器通用：--dry-run（只打印将生成的文件，不落盘）、-y/--yes（非交互）。

快速开始

# 创建工作区
pnpm create vue-workspace my-app
# 或
npx create-vue-workspace@latest my-app

cd my-app
pnpm install
pnpm dev

# 生成代码
cvw g c button            # 独立组件包，自动接线 packages/ui
cvw g pkg hooks --vue     # 通用包
cvw g h theme --pkg hooks # composable
cvw g u array             # 工具函数模块
cvw g v user/list         # 页面 + 自动注册路由
cvw g app admin --port 5174

cvw new 选项

交互式

省略参数时会像 Angular CLI 一样追问，-y 下则直接报错：

cvw g            # 追问：选择生成器
cvw g c          # 追问：组件名称
cvw new          # 追问：工程信息
cvw g list       # 打印生成器清单

自更新

cvw update                  # 检查并升级到最新版本（会先询问确认）
cvw update --check          # 只检查，不升级
cvw update -y               # 不询问，直接升级
cvw update --manager pnpm   # 指定包管理器

说明：

• 升级的是 CLI 自身，不会改动已生成的工程
• 通过 npx / pnpm dlx 临时运行时会提示「无需手动更新」（这类方式每次都拉取最新版）
• 安装方式由可执行文件路径推断（识别 pnpm / yarn / bun 的特征目录），推断不出时回退 npm；实际执行的命令会先打印出来，避免装错位置

名称归一化

输入 Button / button / input_group 都会被归一化：目录 button、组件名 FButton、选择器 f-button、组件文件 components/button.component.tsx。

cvw g h use-theme 与 cvw g h theme 等价（自动去掉 use 前缀）。

错误处理

• 生成器目标已存在 → 报错并退出（退出码 1）
• hook / util 的目标包不存在 → 报错并提示先执行 cvw g pkg <name>
• view 找不到 // cvw:routes 锚点 → 跳过路由注册并提示手写

生成物结构

my-app/
├── apps/
│   └── web/                    # @my-app/web，private，永不发包
│       └── src/
├── packages/
│   ├── ui/                     # @my-app/ui，组件聚合包
│   ├── utils/                  # @my-app/utils，纯 TS 工具
│   └── button/                 # cvw g c 生成，独立组件包
│       ├── index.ts            # 入口：导出组件与 props 类型
│       ├── components/         # 组件实现
│       │   ├── button.component.tsx
│       │   └── button.props.ts
│       ├── composition/        # 可组合逻辑
│       ├── button.scss
│       ├── types.ts
│       ├── __tests__/
│       ├── package.json
│       └── vite.config.ts
├── pnpm-workspace.yaml
├── tsconfig.base.json
└── .changeset/

组件骨架基于《Farris UI Vue 组件开发规范》，并按本仓库约定调整：组件实现（<name>.component.tsx、<name>.props.ts）统一放在 components/ 下，与 composition/、__tests__/ 平级；样式 <name>.scss 保留在组件包根目录。组件名 F 前缀、选择器 f- 前缀。

开发约定

• 内部包引用一律使用 workspace:*，不要写死版本号
• 应用通过 Vite alias 直连 packages/*/src 源码，改库无需重新构建
• 依赖方向单向：utils -> 组件包 -> ui -> apps，禁止反向依赖
• apps/* 已在 .changeset/config.json 中 ignore，不会参与发布

版本管理与发布

pnpm changeset           # 记录变更
pnpm version-packages    # 升版本、生成 CHANGELOG
pnpm release             # 构建并发布到 npm

本地开发（本仓库）

pnpm install
pnpm dev       # 直接运行 CLI（tsx）
pnpm play      # 生成一份真实产物到 playground/ 预览（覆盖全部生成器）
pnpm test      # 单元测试
pnpm typecheck # 类型检查
pnpm build     # unbuild -> dist

发布本 CLI

采用「构建 + 收集」两段式：npm run build 先产出 CLI，再把发包所需文件收集到 dist/create-vue-workspace/，形成一个自包含的可发布包。

dist/create-vue-workspace/
├── package.json      # 已裁剪：无 scripts / devDependencies / private
├── README.md
├── LICENSE
├── dist/index.mjs    # CLI 产物
└── templates/        # 全部模板

发布：

npm login                          # 首次发布需先登录
npm run build                      # unbuild + 收集到 dist/create-vue-workspace/
cd dist/create-vue-workspace
npm pack --dry-run                 # 自检：应只含 dist/ + templates/ + README + LICENSE + package.json
npm publish

或一步到位（先构建再发布）：

npm run publish:dist

约定与注意事项：

• 仓库根 package.json 标记了 private: true，表明它本身不是对外发布的包；请始终从 dist/create-vue-workspace/ 发布
• 升版本在仓库根执行 npm version patch|minor|major，再重新 npm run build
• 暂存目录由每次 npm run build 重建（unbuild 会先清空 dist/），因此发布前务必先 build，避免发出陈旧产物
• 若改为 scoped 包名，需保留 publishConfig.access: "public"

本 CLI 仓库自身未接入 changesets（changesets 只出现在生成物模板中），版本号由 npm version 手动维护。