@wyj-fe/wa-cli

web-admin 脚手架：一键生成完整的前后端工程（Koa + Vue3 + Webpack5 + TypeScript）， 并内置 git 提交规范（husky + commitlint）、eslint、prettier 等工程基建。

定位与 @wyj-fe/web-admin（框架库）分离：web-admin 是"库"，wa-cli 是"脚手架"， 类似 Vue 与 create-vue 的关系。

快速开始

# 1. 生成完整工程（在当前目录下）
npx @wyj-fe/wa-cli create

# 2. 安装依赖（npm/yarn 平铺提升开箱即用；pnpm 会自动生成 .npmrc 依赖提升）
pnpm install   # 或 npm install / yarn

# 3. 启动
pnpm dev        # 开发环境 Koa 服务（8080），TS 源码直接运行
pnpm dev:web    # 前端开发构建（HMR）

# 4. 生产构建与启动（业务侧产物统一输出到 dist/）
pnpm build
pnpm prod       # 等价于 _ENV=prod node dist/server.js

命令

wa-cli create         # 生成完整工程（默认全部生成）
wa-cli create app     # 只生成 app 目录
wa-cli create app config model

生成内容

|—— 根目录
  |—— app
    |—— controller（示例：user.ts）
    |—— service（示例：user.ts）
    |—— middleware
    |—— router（示例：user.ts）
    |—— router-schema（示例：user.ts）
    |—— extend
    |—— pages
      |—— dashboard（router.ts / source 示例）
      |—— widgets
    |—— middleware.ts
    |—— webpack.config.ts
    |—— public（内置静态资源）
  |—— config
    |—— config.default.ts / config.dev.ts / config.prod.ts
  |—— model
    |—— education（领域模型示例，用户只需修改这里即可快速看到效果）
  |—— types
    |—— index.d.ts
  |—— server.ts
  |—— tsconfig.json / tsconfig.node.json（内置 $sys* 与 $business* 别名，编译产物输出到 dist/）
  |—— eslint.config.mjs / .prettierrc.mjs / commitlint.config.js
  |—— .husky（pre-commit 执行 lint:check，commit-msg 执行 commitlint）
  |—— .npmrc（pnpm 场景自动生成，依赖提升）

使用说明

• 用户只需修改 model/ 下的领域模型即可快速看到页面/接口效果
• 自定义页面：app/pages/ 下新增 entry.xxx.ts + 页面组件
• webpack 扩展：app/webpack.config.ts（与内置配置 webpack-merge）
• 业务侧编译产物统一输出到 dist/，不污染源码目录

CJS / ESM 混用与 tsconfig

工程是 CJS 与 ESM 混用的，两套 tsconfig 各司其职：

• tsconfig.json：IDE 类型检查 + 前端（app/pages/**）使用，module: ESNext + moduleResolution: Bundler，由 webpack 处理 ESM； 内置 $sys* 与 $business* 路径别名
• tsconfig.node.json：业务侧服务端编译（server.ts / app/controller / app/service / app/router / app/middleware / config / model）， module: Node16（产物为 CommonJS，输出到 dist/），解析支持包 exports；因此业务侧服务端文件既可用 module.exports/require，也可用 import/export

路径别名

• $sys*：框架内置别名（如 $sysSchemaTable、$sysCurl、$sysTypes），指向已安装的 @wyj-fe/web-admin； 构建期由框架 webpack 自动解析，IDE 由 tsconfig paths 解析
• $business*：业务侧别名（如 $businessPages/*、$businessCommon/*、$businessTypes/*）， 自动指向当前工程 app/pages、types 等目录，构建期同样由框架 webpack 自动解析
• 类型导入：import type { Model } from "@wyj-fe/web-admin/types"（包 exports 已映射，两者均可）

注意：template/ 下的 tsconfig 是为“生成后的工程”准备的，其中路径指向已安装的 @wyj-fe/web-admin。 在 wa-cli 仓库内（未安装依赖）打开时 IDE 对模版文件报“找不到模块/类型”等提示属正常现象， 生成工程并执行 pnpm install 后即消失。

维护

npm pack --dry-run   # 检查发布内容（必须包含 bin/ 与 template/）
npm publish          # 发布到 npm（scope 包需要 --access public）