npm.io
0.2.33 • Published 1h agoCLI

generator-mico-cli

Licence
MIT
Version
0.2.33
Deps
4
Size
2.2 MB
Vulns
0
Weekly
0
SummaryDependencyVersions

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 文件来预设默认值。

配置查找顺序：

  1. 当前目录（或 monorepo 根目录）的 .micorc / .micorc.json
  2. 用户主目录的 .micorc / .micorc.json
完整字段列表
{
  "projectName": "my-app",
  "appId": "portal_dev",
  "packageScope": "@my-company",
  "cdnPrefix": "portal",
  "author": "Team <team@example.com>",
  "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

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

  1. 创建或清空测试目录
  2. 运行 mico create micro-react（自动回车通过 5 个提示）
  3. 运行 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: 构建/工具链变更

Keywords

yeoman-generatorgeneratorcli