create-mayfly-app

create-mayfly-app 是一个用于快速创建项目脚手架的命令行工具，目前内置了 react 与 midway 两种模板。

• 源码类型: ESM ("type": "module")
• 可执行命令: create-mayfly-app（通过 npm / pnpm 全局安装后使用）

使用文档

安装

在任意支持 Node.js 的环境中，将本包安装到全局：

pnpm add -g create-mayfly-app
# 或者
npm install -g create-mayfly-app
# 或者
yarn global add create-mayfly-app

创建新项目

在你希望创建项目的目录下执行：

create-mayfly-app

随后 CLI 会通过交互式命令行，依次询问：

1. Project name: 项目名称，会作为新目录名及 package.json.name。
2. Project description: 项目描述，会写入目标项目 package.json.description（如果模板中使用了变量）。
3. Select a template: 选择模板，当前内置：
   • react
   • midway
4. Server port（仅 midway 模板）: 服务端端口号，用于替换 Midway 模板中的 src/config/config.local.ts 端口配置。

确认后，脚手架会：

1. 在当前目录下创建一个与你填的 Project name 同名的文件夹。
2. 拷贝对应模板目录（如 templates/react、templates/midway）中的全部文件到新项目目录（自动跳过 node_modules）。
3. 修改新项目的 package.json.name 为你输入的项目名。
4. 对指定文件运行 EJS 渲染（变量替换），填充名称、描述、端口等信息：
   • Midway 模板：
     • package.json
     • .github/workflows/deployment-*.yaml
     • k8s/deployment.yaml
     • .devcontainer/devcontainer.json
     • .devcontainer/docker-compose.yml
   • React 模板：
     • package.json
5. Midway 模板会额外更新 src/config/config.local.ts 中的 port 配置。

创建成功后，会输出类似信息：

🎉 Project "your-project-name" created successfully using the "react" template.

接下来进入项目目录，根据模板自身的 README 进行开发即可，例如：

cd your-project-name
pnpm install
pnpm dev

开发文档

本节说明如何本地开发 create-mayfly-app 以及如何扩展/添加新的模板。

本地开发与调试 CLI

1. 克隆仓库并安装依赖

git clone <your-repo-url>
cd create-mayfly-app
pnpm install

2. 本地链接（可选）

为了在本机直接通过 create-mayfly-app 命令调试，可以使用：

pnpm link --global
# 或
npm link

成功后，create-mayfly-app 会指向当前仓库的 bin/index.js。

3. 直接本地运行（不 link）

也可以在仓库根目录使用 Node 直接运行入口文件：

node bin/index.js

代码结构简介

• package.json
  • "main": "bin/index.js"
  • "bin": { "create-mayfly-app": "bin/index.js" }：声明 CLI 命令。
• bin/index.js
  • 使用 commander 定义 CLI，使用 inquirer 做交互。
  • 根据用户选择调用 createMidwayApp 或 createReactApp。
• bin/create.js
  • createMidwayApp：拷贝 Midway 模板、更新包名和端口、渲染 EJS 文件。
  • createReactApp：拷贝 React 模板、更新包名、渲染 EJS 文件。
• bin/copy.js
  • copyTemplate(srcDir, destDir)：递归复制模板目录，自动跳过 node_modules。
• bin/render.js
  • 使用 ejs 渲染指定相对路径下的文件。
  • renderMidwayTemplates：渲染 Midway 项目中一系列配置文件。
  • renderReactTemplates：渲染 React 项目中的 package.json。
• bin/update.js
  • updatePackageName(projectPath, packageName)：修改目标项目的 package.json.name。
  • updateMidwayPort(projectPath, port)：替换 Midway 项目 src/config/config.local.ts 中的 port。
• templates/
  • 内置模板目录（如 react/、midway/），每个模板内部本身就是一个可独立开发的项目。

如何添加 / 扩展模板

假设你希望在现有的 react、midway 之外，增加一个新的模板，例如 vue 或公司自研脚手架。

1. 在 templates 目录下创建新模板

在仓库根目录的 templates/ 下新建一个目录，例如：

templates/
  react/
  midway/
  vue/

templates/vue 目录中可以是任意你想要复制的项目结构，只要满足：

• 脚手架会 原样复制整个目录（除 node_modules）。
• 如需在复制后进行变量替换，可以在文件中使用 EJS 语法，例如：

{
  "name": "<%= name %>",
  "description": "<%= description %>"
}

2. 在 CLI 中暴露新模板选项

编辑 bin/index.js 中模板选择的 choices，增加你的模板名称，例如：

choices: ["react", "midway", "vue"]

3. 在 create.js 中增加对应的创建逻辑

如果新模板只需要「复制 + 改 package.json.name + 渲染某些文件」，可以参考 React 模板的实现：

export function createVueApp({
  templatePath,
  projectPath,
  name,
  description,
}) {
  copyTemplate(templatePath, projectPath);
  updatePackageName(projectPath, name);
  // 如需 EJS 渲染，调用 renderXXXTemplates
}

然后在 bin/index.js 中根据用户选择调用：

if (template === "vue") {
  createVueApp({ templatePath, projectPath, name, description });
}

4. 为新模板配置 EJS 渲染（可选）

如果你希望在新模板中也使用变量替换：

1. 在 bin/render.js 中为模板增加一个类似 renderReactTemplates 的函数。
2. 指定需要渲染的相对路径文件列表。
3. 在对应的 createXXXApp 中调用你的渲染函数。

示例：

export function renderVueTemplates(projectPath, variables) {
  const files = ["package.json"];
  renderTemplateFiles(projectPath, files, variables);
}

5. 模板内部的 README 与使用说明

每个模板目录下可以维护自己的 README.md（例如 templates/react/README.md、templates/midway/README.md）， 用于说明该模板本身的运行方式、开发规范、部署方式等。

脚手架只负责 拷贝 + 变量替换，项目的具体使用说明推荐写在对应模板的 README 中。

常见问题

• Q: 模板中有 node_modules 会怎样？
  A: 脚手架在复制模板时会自动跳过 node_modules 目录，避免体积过大和依赖冲突。

• Q: 想增加更多交互问题（如选择包管理器）？
  A: 可以在 bin/index.js 中的 inquirer.prompt 增加问题项，并在后续 createXXXApp 逻辑中使用这些答案。

• Q: 模板复制后端口没更新？
  A: 目前仅对 Midway 模板的 src/config/config.local.ts 做端口替换，请确认模板路径与文件结构保持一致，或在 updateMidwayPort 中更新对应路径与替换逻辑。