hl-cli

hl-cli 是一个使用 TypeScript 开发的前端项目脚手架 CLI。它支持通过交互问答或完整命令参数创建 Vue 3、React 19 和 Next.js 16 项目，并组合 TypeScript/JavaScript、ESLint + Prettier/Oxlint + Oxfmt、Tailwind CSS 4、状态管理和客户端路由。

环境要求

• Node.js 24.18.0+（不含 Node 25）或 26+（推荐使用项目 Volta 配置的 Node 24.18.0）
• pnpm 11（开发本项目时）

本地开发

pnpm install
pnpm dev
pnpm check

构建后可直接执行：

pnpm build
node dist/cli.js --help

创建项目

无需全局安装即可创建项目：

npm create hl-cli@latest my-app

也可以通过 npx 调用：

npx create-hl-cli@latest my-app

全局安装后可使用 create-hl-cli 或短命令 cfa：

npm install --global create-hl-cli
create-hl-cli my-app

交互模式：

create-hl-cli my-app

使用默认选项快速创建 React + TypeScript 项目：

cfa my-app --yes

用于 CI 或脚本的完整非交互示例：

cfa dashboard \
  --yes \
  --framework next \
  --language ts \
  --tooling oxlint-oxfmt \
  --tailwind \
  --state-management zustand \
  --package-manager pnpm \
  --no-git

只查看执行计划：

cfa my-app --yes --dry-run

参数

| 参数 | 可选值/作用 | 默认行为 | | ------------------------------ | --------------------------------- | ----------------------------- | | [project-name] | 跨平台项目目录名 | 交互询问；配合 --yes 时必填 | | --framework | vue、react、next | react | | --language | ts、js | ts | | --tooling | eslint-prettier、oxlint-oxfmt | eslint-prettier | | --tailwind / --no-tailwind | Tailwind CSS 4 开关 | 不启用 | | --state-management | 按框架选择状态库 | none | | --router / --no-router | React Router 或 Vue Router | 不启用；Next 固定 App Router | | --package-manager | pnpm、npm、yarn | 检测调用来源，否则 pnpm | | --install / --no-install | 是否安装依赖 | 安装 | | --git / --no-git | 是否初始化 Git | 初始化 | | --force | 替换精确的目标目录 | 不覆盖非空目录 | | --dry-run | 仅输出计划 | 不写文件、不执行外部命令 | | -y, --yes | 未提供项使用默认值 | 关闭交互 | | --cwd | 创建项目的基准目录 | 当前目录 | | --verbose | 输出诊断和子进程信息 | 关闭 |

状态管理与 Router 选项按框架约束：

| 框架 | 状态管理 | Router | | ---------- | -------------------------- | ----------------------- | | React 19 | none、zustand、redux | 可选 React Router 8 | | Vue 3 | none、pinia | 可选 Vue Router 5 | | Next.js 16 | none、zustand | 始终使用内建 App Router |

例如，创建 React + Redux Toolkit + React Router 项目：

cfa admin-web --yes --framework react --state-management redux --router

创建 Vue + Pinia + Vue Router 项目：

cfa operations-web --yes --framework vue --state-management pinia --router

创建安全

CFA 先在目标同级的临时目录生成项目文件，再将文件提交到最终目录，依赖安装和 Git 初始化均在最终目录内执行。这保证 pnpm 的 node_modules 与虚拟存储路径稳定，后续可直接执行 pnpm add 或 pnpm install。失败或 Ctrl+C 会清理本次创建的项目；使用 --force 时会先保留原目录备份，只在全部成功后删除，失败则恢复原目录。

pnpm 安装使用显式的 pnpm install --ignore-scripts。当前 Vue/React/Next 模板都使用平台包并已验证可在该安全默认值下完成生产构建；确实需要依赖生命周期脚本时，应先审查依赖，再手动执行和批准所需脚本。

项目结构

src/
├── commands/    # 命令适配与选项收集
├── config/      # 常量、版本与模板标识
├── core/        # 创建用例与目录事务
├── errors/      # 结构化错误模型
├── processor/   # 依赖安装和 Git 后处理
├── prompts/     # 交互问答
├── templates/   # 框架模板与功能转换器
├── types/       # 共享 TypeScript 类型
├── ui/          # 日志、banner、摘要
└── utils/       # 校验与包管理器工具

详细架构与约束见 开发设计文档，开发进度与后续工作见 任务清单。

质量检查

pnpm typecheck
pnpm lint
pnpm test
pnpm build

pnpm check 会按以上顺序执行完整检查。