@morningfast/create-ui

Morningfast UI 公司内部系统脚手架 CLI。

当前阶段用于从 templates/sub-app、templates/main-app、templates/standalone 或 templates/workspace 生成业务项目。脚手架只复制用户选择的模板，不会把 monorepo 根目录、docs 或 packages/create-ui 源码复制进业务项目。

本地构建

在 morningfast-ui 仓库根目录执行：

pnpm --filter @morningfast/create-ui build

构建后会生成：

packages/create-ui/dist/index.js
packages/create-ui/dist/templates/main-app
packages/create-ui/dist/templates/standalone
packages/create-ui/dist/templates/sub-app
packages/create-ui/dist/templates/workspace

使用本地构建产物交互生成：

node packages/create-ui/dist/index.js

也可以直接跑源码调试：

pnpm --filter @morningfast/create-ui dev

交互生成

使用已发布到 npm 的线上版本时，可以在任意希望放置新项目的目录执行：

pnpm dlx @morningfast/create-ui

脚手架会依次询问：

生成类型 standalone(普通单应用)/sub-app(子应用)/workspace(主子应用 monorepo)/main-app(单独主应用)
项目目录
系统名
后端代理地址（main-app / workspace）
是否保留 demo

不确定时直接回车，脚手架会使用默认值。

命令生成

生成默认子应用：

pnpm dlx @morningfast/create-ui my-sub

生成主应用：

pnpm dlx @morningfast/create-ui my-main --template main-app

生成非微前端单应用：

pnpm dlx @morningfast/create-ui my-app --template standalone

生成主应用并移除 demo：

pnpm dlx @morningfast/create-ui my-main --template main-app --no-demo

生成子应用：

pnpm dlx @morningfast/create-ui my-sub --template sub-app

生成业务 monorepo：

pnpm dlx @morningfast/create-ui my-platform --template workspace

在已生成项目根目录更新：

pnpm dlx @morningfast/create-ui --update

也可以在项目外指定 workspace 根目录更新：

pnpm dlx @morningfast/create-ui my-platform --update

--update 可以在 workspace 根目录或独立 main-app/standalone/sub-app 项目根目录执行。workspace 更新会读取根目录 .morningfast-ui.json，再扫描 apps/*/.morningfast-ui.json，按模板类型识别主应用和所有子应用。

默认更新整个 monorepo：

pnpm dlx @morningfast/create-ui --update

只更新主应用：

pnpm dlx @morningfast/create-ui --update --update-target main

只更新所有子应用：

pnpm dlx @morningfast/create-ui --update --update-target sub-apps

更新只覆盖 .morningfast-ui.json 里声明的 managedRoots。业务页面、业务接口模块和业务路由默认不覆盖； package.json 和 .morningfast-ui.json 采用受控合并，保留业务项目 name、自定义字段和本地配置， 只补齐模板依赖、脚本、engines、托管清单和版本信息。

执行 --update 前默认要求 git 工作区干净。人工迁移业务扩展文件后需要和脚手架更新一起验证时，可使用 --update --allow-dirty 显式跳过工作区检查；该参数不会关闭托管文件 hash、退役路径和业务文件保护。 更新还会校验托管文件 hash：如果 src/main.ts、src/App.vue、 vite.config.ts 等托管文件被业务手动改过，即使已经提交，也会停止更新，提示先迁移到 src/setup/index.ts、 src/AppRoot.vue、vite.business.config.ts 等扩展文件。

hash 是按文件完整内容计算的，空格、换行和 CRLF/LF 变化都会触发冲突。冲突时脚手架会提供三份文件：

• base：上一次脚手架托管快照，位于 .morningfast/managed-snapshots/**。
• current：项目当前文件。
• next：本次新模板候选，位于 .morningfast-update-conflicts/**。

如果确认只是格式差异，可以按提示用 cp base current 恢复托管文件后重新更新。

平台运行时已经迁到 @morningfast/platform npm 包。生成出去的业务项目通过依赖升级获取平台能力，不再复制 src/morningfast-core/**。业务代码写在 src/pages/**、src/stores/**、src/api/modules/**、 src/auth/**、src/permissions/**、src/router/**、src/app.config.ts，更新不覆盖已有实现。

根目录文件按 .morningfast-ui.json 的几类规则维护：

• managedRoots：脚手架托管文件或目录，--update 可以覆盖，例如 src/main.ts、src/App.vue、vite.config.ts、tsconfig.app.json。
• ensureRoots：缺失补齐文件或目录，初始化会生成，--update 只在目标不存在时补齐，存在则不覆盖，例如 .gitignore、workspace 的 deploy/、.env.development、.env.test、.env.production、public/release.json、src/auth/**、src/permissions/**、src/router/business-routes.ts 这类业务可接管文件。
• preservedRoots：项目环境、部署和业务代码，--update 不覆盖，例如 .env.development、.env.example、index.html、src/router/static-menus.ts、业务 src/pages。
• mergeFiles：受控合并文件，目前是 .morningfast-ui.json 和 package.json。

后续模板新增文件时先判断职责：入口壳、构建配置、类型声明等会影响统一升级的文件放入 managedRoots； 初始化应带上、后续只想给老项目补缺口且不覆盖业务的文件放入 ensureRoots；项目环境变量、部署配置、业务页面、业务请求和业务状态放入 preservedRoots；需要保留项目自定义字段又要补齐模板字段的文件放入 mergeFiles，并在 CLI 里实现对应合并逻辑。

.gitignore 由业务项目维护。模板只负责创建时提供默认内容，或在老项目完全缺失时补齐；--update 不覆盖已有文件，业务可以持续增加自己的忽略规则。

新项目使用 src/router/static-menus.ts 维护前端静态菜单；auth.mode: 'backend' 配合 auth.menuSource: 'static' 时不会调用菜单接口。--no-demo 会保留最小首页菜单。旧项目执行新版 --update 时，已有 mock-menus.ts 和 business-routes.ts 不会被自动重命名、删除或覆盖；需要使用静态菜单模式时人工迁移。

生成的应用按 mode 提供 .env.development、.env.test 和 .env.production。开发代理目标使用仅供 Vite 配置读取的 MF_PROXY_<SERVICE>_TARGET，路径模式使用 MF_PROXY_<SERVICE>_PATH_MODE=strip|preserve；production mode 只用于本地连接生产环境排查，固定的 vite build 不生成或校验开发代理。

指定系统初始名：

pnpm dlx @morningfast/create-ui my-main --system-name "FMS 管理系统"

指定主应用默认布局：

pnpm dlx @morningfast/create-ui my-platform --template workspace --layout-mode mix

--layout-mode 可选值为 default、side、top、mix。该配置会写入主应用 src/app.config.ts，用户在设置面板保存过布局后，本地偏好优先。

生成完成后进入新项目：

cd my-main
pnpm install
pnpm dev

当前支持的替换

• package.json 的 name 会替换为目标项目名。
• 系统初始名会替换到模板默认标题。
• workspace 会生成 deploy/，并把主应用、默认子应用目录写入通用运维配置。
• deploy 使用 ensureRoots：旧项目已有运维目录时，--update 不覆盖。
• 默认模板是 sub-app，单独主应用需要显式传 --template main-app。
• --no-demo 会删除 src/pages/demo、对应示例路由和示例子应用配置，main-app / sub-app 都适用。
• --update 可在 workspace 或独立 main-app/standalone/sub-app 根目录执行；workspace 支持 all、main、sub-apps 三种更新目标。

不处理的内容

• 接口请求前缀统一放在 src/api/base-urls.ts，默认是 /api；.env.development 只放本地代理目标等开发期变量。
• --update 只覆盖脚手架托管白名单文件，不做业务代码三方合并；业务文件升级通过组件库、迁移说明或 codemod 处理。
• sub-app 当前保持轻量，不包含主应用布局和系统设置；公共组件统一从 morningfast-plus/components 引入。