create-bc-app

内部项目脚手架，用于快速创建 Bochui 相关的前端应用、文档站、库项目和 monorepo 项目。

环境要求

• Node.js 24.18.0
• npm 或其他兼容的包管理器

快速开始

npm create bc-app@latest

指定项目目录：

npm create bc-app@latest my-project

CLI 会依次询问项目名、包名、模板类型和模板变体。创建完成后进入项目目录安装依赖：

cd my-project
pnpm install
pnpm dev

文档类模板使用 docs:dev 启动，请以生成项目的 package.json 为准。

创建 Vue TypeScript 或 Monorepo 浏览器应用时，CLI 还会询问是否添加 @fsdev/fs-log 离线埋点工具。选择添加后，模板会生成最小初始化模块，并从 VITE_FS_LOG_API_KEY 读取项目 Key；请向埋点平台负责人申请 Key 后写入项目的 .env.local。非交互创建可以使用 --fs-log 或 --no-fs-log，未指定时默认不添加：

npm create bc-app@latest my-project -- --template vue --variant ts --communication none --fs-log

可用模板

| 模板 | 变体 | 说明 | | ------------- | ------------------------ | ----------------------- | | Vue | ts | Vue 3 + Vite 应用模板 | | Docs | vitepress / vuepress | 文档站模板 | | ProtoCut | 2d / 3d | ProtoCut 业务模板 | | LaserLib | - | LaserLib 库模板 | | Data Server | - | 数据服务模板 | | Monorepo | - | pnpm workspace 多包模板 |

本地开发

安装依赖：

pnpm install

构建 CLI：

pnpm run build

本地运行构建后的 CLI：

node index.js demo-project

CBA 本身的质量检查

CBA 根项目与 vue-ts 模板使用同一套代码质量基线，针对 CLI/Node.js 源码启用 ESLint、Prettier、Commitlint，以及 Husky + lint-staged 提交门禁。模板目录和生成缓存不会被根项目 ESLint 扫描。

pnpm run lint
pnpm run format:check
pnpm test

修改代码后可使用 pnpm run format 自动格式化。提交信息支持公司工单格式、CodeReview，以及 docs、style、test、chore、release 类型，例如 TASK#123: 完善 CLI 校验 或 chore: 更新依赖。

项目入口为 index.js，实际运行构建产物 dist/index.mjs。源码位于 src/，模板文件位于 templates/。

更新历史项目能力

在需要更新的项目目录中运行：

npx create-bc-app@latest update

CLI 会打开多选列表，目前支持：

• Git 提交门禁：Husky、lint-staged 和 Commitlint。
• 代码质量：同时更新 ESLint 和 Prettier。
• 前端工具链：更新 Node、pnpm、Vite、Vitest 等工具版本，同时合并 pnpm workspace 的 minimumReleaseAge 和 minimumReleaseAgeExclude；保留已有 packages、overrides、注释和其他自定义配置，不修改 Vite、构建或测试配置。
• TypeScript：只更新 TypeScript、vue-tsc 和 @types/node 版本，不修改任何 tsconfig。
• 样式质量：Stylelint 和 Vue SFC 样式检查。
• GitLab CI：覆盖 .gitlab-ci.yml，使存量项目同步当前模板流水线配置。
• VS Code：更新 .vscode/extensions.json 和 .vscode/settings.json；已有文件会在计划中明确提示后覆盖。

CLI 会根据依赖和 workspace 结构识别 Vue TS、VitePress、VuePress、Data Server 或 Monorepo，但自动识别结果只作为交互列表的默认值。用户必须确认项目类型后，CLI 才会展示该类项目支持的能力并生成更新计划。非交互执行必须通过 --template 和 --variant 显式确认：

npx create-bc-app@latest update ./docs --template docs --variant vitepress
npx create-bc-app@latest update ./data --template dataServer
npx create-bc-app@latest update ./workspace --template monorepo

建议先使用 --dry-run 检查更新计划。CBA 对所选能力采用权威迁移：已有受管配置会被模板配置覆盖，已知旧配置和旧依赖会被删除；CLI 会在写入前明确列出这些变化，但不要求额外的覆盖参数。

依赖发生变化时可添加 --update-lockfile，CLI 会根据项目包管理器执行 lockfile-only 更新；命令失败时会恢复本轮配置、package.json 和 lockfile。

Quality 迁移会删除旧版 @typescript-eslint/eslint-plugin、@typescript-eslint/parser 和 @rushstack/eslint-patch，只保留 flat config 使用的 typescript-eslint。Git Hooks 迁移会删除旧 Commitlint 配置变体和旧 commitlint 包，只保留 commitlint.config.mjs 与 @commitlint/cli。已有 pre-commit、commit-msg 会被模板 hook 覆盖；pre-push 等其他 hooks 保持不变。

也可以指定项目目录：

npx create-bc-app@latest update ./old-project

CLI 会先汇总所选能力涉及的配置文件和 package.json 变化，只显示实际发生变化的文件，然后统一确认和写入。任一文件写入失败时会恢复本次更新前的内容。

自动化场景可以使用弱化的可选参数跳过多选：

npx create-bc-app@latest update ./old-project --select git-hooks,quality,toolchain,tsconfig,stylelint,ci,vscode --force

旧快捷命令继续保留一个兼容周期，但已统一映射到 profile update，并会输出弃用提示：

npx create-bc-app@latest update-eslint ./old-project
npx create-bc-app@latest update-prettier ./old-project
npx create-bc-app@latest update-commitlint ./old-project

--force 会跳过最终确认，但仍会输出更新计划。--dry-run 保证不写入。--select 使用逗号分隔，可用值为 git-hooks、quality、toolchain、tsconfig、stylelint、ci 和 vscode。选择 toolchain 时会结构化合并上述 pnpm workspace 字段；除此之外，Update 不修改 tsconfig*.json、vite.config.*、workspace、构建或测试配置。GitLab CI 和 VS Code 配置会在计划中明确提示后覆盖。

能力配置以识别出的对应模板为来源，避免将 Vue SPA 配置覆盖到 Docs、Data Server 或 Monorepo。默认不安装依赖；仅在显式使用 --update-lockfile 时执行 lockfile-only 更新，且始终禁用 install scripts。

项目结构

src/
  cli/       参数解析与交互提示
  config/    模板配置、模板映射、可更新文件 registry
  core/      项目创建、模板复制、配置文件更新、package.json 处理
  templates/ 模板后处理器
  utils/     文件、路径、日志、校验工具
templates/   生成项目的模板源文件
dist/        构建产物

新增或修改模板

1. 在 templates/ 下新增或调整模板目录。
2. 在 src/config/templateMap.ts 中维护模板名到目录名的映射。
3. 在 src/config/templateConfig.ts 中维护展示名称、变体和按变体注入的依赖。
4. 如模板需要生成动态文件，在 src/templates/ 下添加处理器，并注册到 src/templates/index.ts。
5. 运行 pnpm run build，再用 node index.js <project-name> 验证生成结果。

新增可更新配置文件

1. 在 src/config/updateCapabilities.ts 中维护公共能力定义。
2. 在 src/config/updateProfiles.ts 中为适用模板声明文件、旧配置和 package.json 补丁。
3. 确认 profile 自动识别规则位于 src/core/resolveUpdateProfile.ts，无法可靠识别时应安全拒绝。
4. 在 test/cli.test.mjs 中覆盖 create、dry-run、覆盖迁移、幂等、回滚和 lockfile 边界。
5. 运行 pnpm run build、pnpm test 和对应生成模板的完整检查命令。

发布

发布前确认版本、构建产物和模板文件均已更新：

pnpm run build
pnpm run deploy

deploy 使用 release-it，发布配置见 package.json 与 .release-it.json。