generator-mico-cli

v0.2.32

Published

2 days ago

Yeoman generator for Mico CLI projects

0High
0Medium
0Low

mico_team

yeoman-generator generator cli

Mico CLI Generator

用于搭建基于 TypeScript 的 Node.js CLI 项目的 Yeoman 生成器。

文档索引

项目总览与设计

| 文档 | 说明 | |---|---| | docs/mico-cli.md | mico CLI 整体能力、命令清单（create / list / doctor / --verbose / --dry-run）与子进程调用约定 | | docs/architecture.md | 项目架构、模块职责、关键约定、依赖关系 | | docs/generators.md | 各生成器的 prompt / 模板变量 / 联动修改细节（生成器之间的协作总览） | | docs/configuration.md | .micorc / .micorc.json 配置字段、加载顺序与默认值 | | docs/testing.md | Vitest + yeoman-test 测试体系、目录结构与 Mock 策略 | | docs/scripts.md | sync:subapp-react-template 与 verify:micro-react 辅助脚本 |

各生成器使用说明（按生成器拆分，建议先于代码改动阅读）

| 生成器 | 使用说明 | 仓库内就近说明 | |---|---|---| | micro-react（qiankun Monorepo 基座） | docs/micro-react-generator.md | generators/micro-react/README.md | | subapp-react（在已有 Monorepo 中新增 React 子应用） | docs/subapp-react-generator.md | generators/subapp-react/README.md | | h5-react（Umi 4 H5 Monorepo 基座 + 联动 subapp-h5） | docs/h5-react-generator.md | —（模板内置 README，由生成器写入目标项目根目录） | | subapp-h5（在 H5 Monorepo 中新增 Umi 子应用） | docs/subapp-h5-generator.md | —（无独立 README，约定见上文与 templates/.cursor/rules/） | | subapp-umd（UMD 组件包，<script> 加载场景） | —（详见本 README 「UMD 组件包生成器」一节） | generators/subapp-umd/README.md |

要求

Node >= 18

安装和使用

pnpm install -g generator-mico-cli

包装器 CLI

全局安装后，mico 命令可用于运行内置的 Yeoman 生成器。

mico create subapp-react

列出所有可用的生成器：

mico list

使用详细输出模式（显示文件处理过程）：

mico create micro-react --verbose

预览模式（只显示将创建的文件，不实际创建）：

mico create micro-react --dry-run

检查环境依赖：

mico doctor

执行配置任务（如配置自托管 Multica Desktop）：

mico setup multica-desktop

详见下文 Multica Desktop 自托管配置。

配置文件

可以在项目目录或用户主目录创建 .micorc 或 .micorc.json 文件来预设默认值。

配置查找顺序：

当前目录（或 monorepo 根目录）的 .micorc / .micorc.json
用户主目录的 .micorc / .micorc.json

完整字段列表

{
  "projectName": "my-app",
  "appId": "portal_dev",
  "packageScope": "@my-company",
  "cdnPrefix": "portal",
  "author": "Team <[email protected]>",
  "initialSubAppName": "app",
  "initialSubAppDevPort": "8000",
  "defaultSubappName": "subapp",
  "devPort": "8010",
  "defaultUmdName": "my-widget",
  "umdDevPort": "9100"
}

| 字段 | 类型 | 适用生成器 | 说明 | 默认值 | |------|------|-----------|------|--------| | projectName | string | micro-react、h5-react | 项目名称 | 当前目录名 | | appId | string | micro-react | 开发环境 window.__MICO_CONFIG__.appId（请求代理等） | portal_dev | | packageScope | string | 所有 | 包作用域（如 @my-company） | micro-react / h5-react: 见各生成器提示；其他: 多从根 package.json 检测 | | cdnPrefix | string | micro-react、h5-react | CDN 路径前缀（如 portal、admin/v2），写入 CICD 脚本中的 CDN_PUBLIC_PATH 等 | 空字符串 | | author | string | micro-react、h5-react、subapp-h5 | 作者信息 | 见各生成器提示 | | initialSubAppName | string | h5-react | 首个子应用目录名（apps/ 下） | app | | initialSubAppDevPort | string | h5-react | 首个子应用独立 pnpm dev 端口 | 8000 | | defaultSubappName | string | subapp-react、subapp-h5 | 子应用默认名称 | subapp-react: subapp；subapp-h5: app | | devPort | string | subapp-react、subapp-h5 | 子应用开发端口 | subapp-react: 8010；subapp-h5: 8000 | | defaultUmdName | string | subapp-umd | UMD 包默认名称 | my-widget | | umdDevPort | string | subapp-umd | UMD 包开发端口 | 9100 |

所有字段均为可选，未配置时使用默认值或交互式提示。

Monorepo 项目生成器 (micro-react)

创建基于 qiankun 微前端架构的完整 Monorepo 项目：

mkdir my-project && cd my-project
mico create micro-react

生成的项目包含：

主应用 (layout) - qiankun master
@mico-platform/ui、@mico-platform/theme
Turborepo + pnpm Workspace
Husky + Commitlint
@common-web/sentry 错误监控与 SourceMap 上传

若需要 Umi 4 H5 多应用 + 开发网关 / dev 预设，请使用 h5-react（见 docs/h5-react-generator.md）。

React 子应用生成器（subapp-react）

该生成器会复制 apps/homepage 模板为新的子应用，并替换标识字符串。 config/ 目录下的多环境配置会完整保留。

cd <monorepo-root>
mico create subapp-react

详见 docs/subapp-react-generator.md。

H5 Monorepo 生成器（h5-react）

用于创建 Umi 4 多子应用 H5 仓库：pnpm workspace、Turborepo、开发网关（page.config.ts）、dev 预设，并联动 subapp-h5 生成首个 apps/<名>/ 子应用。内部包含 11 个 workspace 包：domain（API/CDN/多语言基址）、js-bridge（H5 ↔ 原生通信）、request（基于 Umi 的统一请求；isShowLoading 默认 true）、common-intl（init() 经 js-bridge.getUserInfo 取语言）、components（沉浸式 H5 布局）、constant / deeplink、umi-config（子应用 config/*.ts 全部委托到此包的工厂，并内置 Sentry sourcemap 上传插件 src/plugins/apply-sentry-plugin.ts）、utils、eslint、typescript。模板内已接入 @common-web/sentry（子应用布局错误边界、生产构建 externals），根目录提供 build / build:development / build:testing / build:production 与 CICD 各环境对应；环境变量 .env.development / .env.testing / .env.production 集中维护在仓库根，lint-staged 通过 .lintstagedrc.js 集中维护。pnpm-workspace.yaml 的 catalog 钉扎 umi、react*、tailwindcss、tailwindcss-safe-area、@umijs/plugins、cross-env、@common-web/sentry 等版本（@sentry/webpack-plugin 仅装在 packages/umi-config，不在仓库根、不在子应用）。

mkdir my-h5 && cd my-h5
mico create h5-react

若当前目录已存在 pnpm-workspace.yaml，需使用 mico create h5-react --force（会覆盖已有文件，请谨慎）。

详见 docs/h5-react-generator.md。

H5 子应用生成器（subapp-h5）

在由 h5-react 初始化的 Monorepo 根目录执行，在 apps/<名>/ 下新增 Umi 子应用，并更新根目录 page.config.ts、dev.preset.json。子应用模板默认：

config/ 全部委托到 <%= packageScope %>/umi-config（createBaseConfig / createDevConfig / createProConfig / createDevelopmentConfig / createTestingConfig / createProductionConfig）；不再在子应用里重抄 plugins、request: {}、externals 或 Sentry 上传逻辑——createProductionConfig 自动接入 sourcemap 上传（需 SENTRY_AUTH_TOKEN）
src/intl.ts + src/app.tsx：init({ tag, indexedDBParams }) 取得 { fetchMultilingualData, i18n }，首屏前 fetchMultilingualData()；init() 内部经 <%= packageScope %>/js-bridge 的 getUserInfo() 取语言
src/layouts/index.tsx：<SentryErrorBoundary><Outlet/></SentryErrorBoundary>
src/services/<域>.ts 就近定义请求/响应 interface 与服务函数；mock/<域>.ts 复用 <%= packageScope %>/utils/mock 的 baseUrl / tryProxy（zod 入参校验、mockjs 占位、可选 ?remote= 透传到真实后端）
Tailwind 3 + tailwindcss-safe-area：tailwind.css（含 font-size: 16px; + 1vw 适配）、tailwind.config.js（ESM，扫描 ./src/** + packages/components/src，挂安全区插件）
config/routes.ts 仅含静态基础路由；动态菜单可与 window.__MICO_MENUS__ 等配合

cd <h5-monorepo-root>
mico create subapp-h5

详见 docs/subapp-h5-generator.md。

UMD 组件包生成器

在 Monorepo 的 packages/ 目录下创建 UMD 格式的组件包，使用 Webpack 构建。适用于通过 <script> 标签加载的场景（如主应用菜单挂载组件、第三方系统嵌入 Widget 等）。

cd <monorepo-root>
mico create subapp-umd

生成器会提示输入：

Package name — 包名（如 my-widget）
UMD global variable name — 全局变量名（如 MyWidget）
Package scope — 包作用域（自动从根 package.json 检测）
Dev server port — 开发端口（默认 9100）

生成的包支持：

pnpm dev — 启动 webpack-dev-server，同时提供 HTML 预览页和 UMD JS 文件
pnpm build — 构建生产环境 UMD 产物到 dist/

开发模式下：

| URL | 用途 | |---|---| | http://localhost:<port>/ | HTML 预览页，独立调试 | | http://localhost:<port>/<name>.umd.js | UMD JS 文件，供主应用通过 jsUrls 联调 |

DevTools Sources 面板中可在 webpack://<name>/src/ 下定位原始 TypeScript 源码进行断点调试。

Multica Desktop 自托管配置（`setup multica-desktop`）

Multica Desktop 默认连接 Multica Cloud；要让它指向公司自托管实例，需要在用户目录写入 ~/.multica/desktop.json（配置规范见官方文档）。mico setup multica-desktop 把这个一次性配置封装成了跨平台命令：

mico setup multica-desktop

写入的默认内容（指向米可自托管地址）：

{
  "schemaVersion": 1,
  "apiUrl": "https://multica-api.micoplatform.com",
  "appUrl": "https://multica.micoplatform.com"
}

wsUrl 不写，由 Desktop 按官方规则从 apiUrl 自动推导为 wss://multica-api.micoplatform.com/ws。

目标路径（跨平台）

| 平台 | 实际路径 | |---|---| | macOS | /Users/<Username>/.multica/desktop.json | | Linux | /home/<Username>/.multica/desktop.json | | Windows | C:\Users\<Username>\.multica\desktop.json |

路径统一通过 os.homedir() 解析，三平台无需任何额外参数。

默认行为

如果文件不存在：创建 .multica 目录，写入默认配置。
如果文件已存在：先备份为 desktop.json.bak.<时间戳>，再覆盖。
完成后需要重启 Multica Desktop 让配置生效。

可选参数

| 参数 | 说明 | |---|---| | --dry-run | 仅预览输出内容，不写盘 | | --no-backup | 已存在时直接覆盖，不生成 .bak | | --force | 同 --no-backup，沿用全局 --force 语义 | | --api-url=<url> | 覆盖默认 apiUrl | | --app-url=<url> | 覆盖默认 appUrl | | --ws-url=<url> | 显式设置 wsUrl（不传则由 Desktop 自动推导） |

示例：

mico setup multica-desktop --dry-run
mico setup multica-desktop --no-backup
mico setup multica-desktop \
  --api-url=https://api.your-domain \
  --app-url=https://your-domain

开发指南

环境准备

# 1. 安装依赖
pnpm install

# 2. 将本地包链接到全局
npm link

# 3. 验证链接成功
mico --version

链接成功后，mico 命令会使用本地代码，可以直接修改代码并测试：

# 测试 micro-react 生成器
mkdir test-project && cd test-project
mico create micro-react

# 测试 subapp-react 生成器（需在已有 monorepo 中执行）
mico create subapp-react

# 测试 h5-react（空目录）
mico create h5-react

# 测试 subapp-h5（需在含 apps/ 的 H5 monorepo 根目录执行）
mico create subapp-h5

# 测试 subapp-umd 生成器（需在已有 monorepo 中执行）
mico create subapp-umd

调试完成后，取消全局链接：

npm unlink -g generator-mico-cli

运行测试

项目使用 Vitest + yeoman-test 进行单元测试和集成测试：

# 运行全部测试
pnpm test

# watch 模式
pnpm test:watch

测试目录结构：

| 目录/文件 | 说明 | |----------|------| | tests/unit/utils.test.js | lib/utils.js 的单元测试 | | tests/unit/setup-multica-desktop.test.js | lib/setup-multica-desktop.js 单元测试（隔离 home 目录，覆盖首次写入 / 备份 / --no-backup / --dry-run） | | tests/integration/micro-react.test.js | micro-react 生成器集成测试 | | tests/integration/subapp-react.test.js | subapp-react 生成器集成测试 | | tests/integration/h5-react.test.js | h5-react 生成器集成测试 | | tests/integration/subapp-h5.test.js | subapp-h5 生成器集成测试 | | tests/integration/subapp-umd.test.js | subapp-umd 生成器集成测试 | | tests/integration/mico-cli.test.js | mico 入口子进程测试（help / version / list / create / doctor / setup） | | tests/helpers/setup.js | 测试共享工具（路径常量、monorepo fixture 工厂） | | tests/helpers/mico-subprocess.js | 子进程运行 bin/mico.js 工具函数 |

Scripts 说明

| 脚本 | 命令 | 说明 | |------|------|------| | sync:subapp-react-template | pnpm run sync:subapp-react-template -- <source-path> | 将源项目的 apps/homepage 同步到 subapp-react 模板目录，忽略清单见 generators/subapp-react/ignore-list.json | | verify:micro-react | node scripts/verify-micro-react.js [test-dir] | 端到端验证 micro-react + subapp-react 生成器，自动创建项目并回车通过所有提示 |

verify-micro-react.js

自动化验证脚本，依次执行：

创建或清空测试目录
运行 mico create micro-react（自动回车通过 5 个提示）
运行 mico create subapp-react（自动回车通过 4 个提示）

测试目录支持三种方式指定：

命令行参数：node scripts/verify-micro-react.js /path/to/dir
环境变量：VERIFY_TEST_DIR=/path node scripts/verify-micro-react.js
默认值：../test-app2

sync-subapp-react-template.js

从源 monorepo 项目同步 apps/homepage 到生成器模板目录：

# 通过环境变量
SOURCE_PROJECT_ROOT=<source-path> pnpm run sync:subapp-react-template

# 通过命令行参数
pnpm run sync:subapp-react-template -- <source-path>

会自动记录源仓库的 git commit 信息到 .template-version.json。

项目结构

mico-cli/
├── bin/mico.js              # CLI 入口（命令解析、生成器调度、setup 子命令分发）
├── lib/
│   ├── utils.js             # 共享工具函数（字符串转换、文件处理、npm 版本查询、配置加载）
│   └── setup-multica-desktop.js  # `mico setup multica-desktop` 核心实现
├── generators/
│   ├── micro-react/         # Monorepo 项目生成器（qiankun）
│   ├── subapp-react/        # React 子应用生成器
│   ├── h5-react/            # H5 Monorepo（Umi + 网关 / 预设）
│   ├── subapp-h5/           # H5 Umi 子应用
│   └── subapp-umd/          # UMD 组件包生成器
├── scripts/                 # 辅助脚本
├── tests/                   # 测试文件
├── docs/                    # 功能文档
└── vitest.config.js         # 测试配置

提交规范

请使用语义化提交信息：

feat: 添加新功能
fix: 修复 Bug
refactor: 代码重构
docs: 文档更新
test: 测试相关
chore: 构建/工具链变更