@wyfe/create-app

往约工程脚手架 👷 多模板前端项目生成工具

一个基于 Node.js 的前端脚手架工具，支持通过交互式命令行快速生成符合团队规范的标准化前端项目。内置多种项目模板，支持自定义模板扩展。

✨ 特性

• 🚀 快速启动 - 交互式命令行，快速生成项目
• 📦 多模板支持 - 内置 4 种项目模板（基础、H5、PC、小程序）
• 🎨 模板变量 - 支持 EJS 模板语法，动态渲染项目配置
• 🔧 标准化 - 生成的项目符合团队开发规范
• 🛠️ 易于扩展 - 支持自定义模板，灵活适配不同需求

📦 安装与使用

方式一：使用 create 命令（推荐）

# 使用 pnpm（推荐）
pnpm create @wyfe/app

# 使用 npm
npm create @wyfe/app@latest

# 使用 yarn
yarn create @wyfe/app

# 使用 deno
deno run -A npm:@wyfe/create-app

# 使用 pnpm dlx
pnpm dlx @wyfe/create-app

💡 说明：pnpm create @wyfe/app 会自动解析为安装并执行包 @wyfe/create-app。

方式二：全局安装

# 全局安装
pnpm add -g @wyfe/create-app

# 使用
create-app

系统要求

• Node.js >= 18.18.0

🛠️ 本地开发

如果你想要参与项目开发或调试脚手架功能，可以克隆项目到本地进行开发。

环境准备

# 克隆项目（如果是在 monorepo 中，直接进入目录）
cd packages/create-app

# 安装依赖
pnpm install

开发模式

# 方式一：使用项目脚本
pnpm dev

# 方式二：直接使用 tsx 运行源码
npx tsx src/index.ts

# 方式三：使用 node 运行编译后的代码
pnpm build
node dist/index.js

构建项目

# 构建 TypeScript 代码并复制模板文件
pnpm build

构建产物会输出到 dist/ 目录，包括：

• dist/index.js - 编译后的主入口文件
• dist/templates/ - 模板文件目录

📖 使用示例

交互式创建项目

运行命令后，会进入交互式创建流程：

pnpm create @wyfe/app

步骤一：输入项目名称

? 填写项目名（规范：业务线_端_项目名）
> wangyue_h5_user

💡 命名规范：建议使用 业务线_端_项目名 的格式，例如 wangyue_h5_user、wangyue_pc_admin 等。

步骤二：输入 OSS BucketName（可选）

? 填写OSS BucketName（非必填）
> front-wy-h5

💡 说明：OSS BucketName 用于项目部署时的静态资源存储配置，非必填项。

步骤三：选择项目模板

? 选择项目模板
  ❯ 通用基础项目
    前端H5项目
    前端PC项目
    前端小程序项目

可用模板

| 模板名称 | 模板 ID | 说明 | |---------|---------|------| | 通用基础项目 | project_basic | Vue 3 + TypeScript + Vite 基础模板，适合快速开始 | | 前端H5项目 | project_h5 | H5 移动端项目模板，集成 Vant UI、路由、状态管理等 | | 前端PC项目 | project_pc | PC 端管理后台模板，集成 Element Plus、路由、状态管理等 | | 前端小程序项目 | project_mp | 小程序项目模板，支持微信/抖音小程序 |

生成完成

项目生成成功后，会显示以下提示信息：

✅ wangyue_h5_user 初始化完成

可执行以下命令
   cd wangyue_h5_user
   pnpm i
   pnpm dev

开始开发

# 进入项目目录
cd wangyue_h5_user

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

🎨 自定义模板

如果你需要创建自定义的项目模板，可以按照以下步骤操作：

1. 创建模板目录

在 src/templates/ 目录下创建新的模板目录：

mkdir -p src/templates/my_custom_template

2. 模板文件结构

src/templates/my_custom_template/
├── package.json.ejs          # 使用 EJS 语法的配置文件
├── README.md.ejs             # 项目说明文件
├── vite.config.ts            # 普通文件，直接复制
├── _gitignore                # 以 _ 开头，复制时会转为 .gitignore
├── src/
│   ├── main.ts
│   └── App.vue
└── public/
    └── favicon.ico

3. 模板变量

在 .ejs 文件中可以使用以下内置变量：

• <%= projectName %> - 项目名称（用户输入）
• <%= bucketName %> - OSS BucketName（用户输入，可为空）

示例：package.json.ejs

{
  "name": "<%= projectName %>",
  "version": "0.0.0",
  "description": "Custom project template",
  "scripts": {
    "dev": "vite",
    "build": "vite build"
  }
}

示例：README.md.ejs

# <%= projectName %>

这是一个自定义项目模板。

<% if (bucketName) { %>
OSS Bucket: <%= bucketName %>
<% } %>

4. 特殊文件命名规则

• 以 _ 开头的文件/目录：复制时会自动转换为以 . 开头

  • _gitignore → .gitignore
  • _env.example → .env.example
  • _eslintrc.js → .eslintrc.js

• .ejs 文件：使用 EJS 模板引擎渲染后，移除 .ejs 后缀

  • package.json.ejs → 渲染后生成 package.json
  • README.md.ejs → 渲染后生成 README.md

5. 注册模板

在 src/index.ts 的模板选择选项中添加新模板：

const template = await select({
  message: '选择项目模板',
  options: [
    { value: 'project_basic', label: '通用基础项目' },
    { value: 'project_h5', label: '前端H5项目' },
    { value: 'project_pc', label: '前端PC项目' },
    { value: 'project_mp', label: '前端小程序项目' },
    { value: 'my_custom_template', label: '我的自定义模板' }, // 新增
  ],
})

6. 注意事项

• ⚠️ 模板目录中的 .git 目录会被自动忽略，不会复制到新项目
• ✅ 模板文件支持嵌套目录结构
• ✅ 支持二进制文件（图片、字体等）的复制
• ✅ 确保模板目录结构完整，包含必要的配置文件

🔧 技术实现

核心依赖

• @clack/prompts - 现代化的交互式命令行工具
• ejs - 嵌入式 JavaScript 模板引擎
• picocolors - 轻量级终端颜色库

工作流程

1. 交互式输入 - 使用 @clack/prompts 收集用户输入
2. 目录检查 - 验证目标目录是否为空
3. 模板复制 - 递归复制模板文件到目标目录
4. 文件处理 -
   • 将 _ 开头的文件转换为 . 开头
   • 使用 EJS 渲染 .ejs 文件
   • 删除原始 .ejs 文件
5. 完成提示 - 显示后续操作指引

❓ 常见问题

Q: 目标目录已存在且非空怎么办？

A: 脚手架会检查目标目录，如果目录已存在且非空，会取消操作并提示错误。请确保目标目录为空或不存在。

Q: 如何修改模板变量？

A: 目前支持 projectName 和 bucketName 两个变量。如需扩展，可以修改 src/index.ts 中的 ejs.render() 调用，传入更多变量。

Q: 模板文件中的 .git 目录会被复制吗？

A: 不会。脚手架会自动忽略模板目录中的 .git 目录，避免将模板的历史记录复制到新项目。

Q: 如何更新已发布的模板？

A: 修改 src/templates/ 下的模板文件后，重新构建并发布包即可。构建时会自动将模板文件复制到 dist/templates/。

📄 许可证

MIT

🤝 贡献

欢迎提交 Issue 和 Pull Request！

Made with ❤️ by @wyfe team