# front-template-cli

**Repository Path**: hokichen/front-template-cli

## Basic Information

- **Project Name**: front-template-cli
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-09-11
- **Last Updated**: 2026-09-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# cyzn

公司内部前端脚手架 CLI。基于模板目录动态注册命令，**模板目录名 = 命令名**，新增模板无需修改任何 CLI 代码。

## 特性

- `cyzn <模板名> <项目名> --title <标题>` 创建项目（如 `cyzn template my-app --title 订单管理平台`）
- **默认不安装依赖**，只拷贝渲染模板；需要时加 `--install` 才安装
- `--title <标题>` **必填**，`--port <端口>` 可选，用于自定义浏览器标题与开发端口
- 模板继承：`meta.json` 中 `extends` 可复用其他模板的工程配置，只覆盖差异文件
- 模板中 `_` 开头的文件生成时重命名为 `.` 开头（`_gitignore` → `.gitignore`）
- 生成的项目自动删除 `.git`，并按 `svn-ignore.txt` 设置 `svn:ignore`
- 统一使用 TypeScript + npm

## 安装

```bash
npm install cyzn -g
```

本地开发调试：

```bash
npm install
npm link        # 之后可直接使用 cyzn 命令
```

## 使用

```bash
# --title 必填；默认只拷贝模板，不装依赖
cyzn template my-app --title 订单管理平台
# 输出：cd my-app && npm install && npm start

# 需要自动装依赖时（固定使用 npm）
cyzn template my-app --title 订单管理平台 --install
# 输出：cd my-app && npm start

# 自定义标题与开发端口
cyzn template my-app --title 订单管理平台 --port 9000
# 生成项目 .env 中 REACT_APP_TITLE=订单管理平台、PORT/WDS_SOCKET_PORT=9000

# 查看模板列表 / 版本 / 帮助
cyzn list
cyzn -v
cyzn -h
```

### 命令一览

| 命令 | 作用 |
|---|---|
| `npm install cyzn -g` | 全局安装脚手架 |
| `cyzn template <项目名> --title <标题>` | 用 `templates/template/` 模板创建项目（不装依赖） |
| `cyzn <其他模板名> <项目名> --title <标题>` | 用 `templates/<其他模板名>/` 创建项目 |
| `cyzn <模板名> <项目名> --title <标题> --install` | 创建项目并自动安装依赖 |
| `cyzn <模板名> <项目名> --title <标题> --port <端口>` | 自定义浏览器标题与开发端口 |
| `cyzn list` | 列出所有可用模板 |
| `cyzn -v` / `--version` | 查看版本 |
| `cyzn -h` / `--help` | 查看帮助 |

通用选项（所有模板命令都支持）：

- `--install`：创建后自动安装依赖（**默认不装**，固定使用 `npm`）
- `--title <标题>`：**必填**。浏览器标签页标题，写入生成项目 `.env` 的 `REACT_APP_TITLE`，再由 `public/index.html` 的 `<title>%REACT_APP_TITLE%</title>` 注入
- `--port <端口>`：本地开发端口，写入生成项目 `.env` 的 `PORT` 与 `WDS_SOCKET_PORT`；默认 `8008`

> 不支持 `--pm` / `--js`：包管理器固定为 npm，语言固定为 TypeScript。

> 注意：`cyzn` 后面必须带模板名或 `list`，不带时输出帮助信息。不存在 `cyzn <项目名>` 这种省略模板名的形式。

## 项目结构

```
cyzn/
├── package.json
├── bin/
│   └── index.js              # CLI 入口，动态注册模板命令
├── src/
│   ├── commands/
│   │   └── create.js         # 为每个模板注册 commander 子命令
│   ├── install.js            # 依赖安装（固定 npm，仅 --install 时调用）
│   ├── render.js             # 模板渲染拷贝（ejs、extends、下划线重命名）
│   ├── svn.js                # 删除 .git、设置 svn:ignore
│   ├── logger.js             # 日志封装
│   └── templates.js          # 扫描 templates 目录
├── templates/
│   └── template/             # cyzn template <项目名>（当前仅此一个模板）
└── README.md
```

## 新增模板（零代码改动）

1. 在 `templates/` 下新建目录，**目录名即为命令名**，例如 `templates/admin/` → `cyzn admin <项目名>`（当前只有 `templates/template/`）。
2. 在目录下新建 `meta.json`：

   ```json
   {
     "name": "admin",
     "description": "运营后台模板",
     "extends": null
   }
   ```

3. 放入模板文件。文件命名约定：
   - `*.ejs` 会作为 EJS 模板渲染，可用变量 `projectName`、`title`、`port`，渲染后去掉 `.ejs` 后缀（`package.json.ejs` → `package.json`）。
   - **模板根目录**下 `_xxx` 会重命名为 `.xxx`（`_gitignore` → `.gitignore`），避免 npm 发布丢失点文件。只处理第一层，源码里的下划线文件（如 `src/styles/_mixin.scss`）保持原样。
   - `meta.json`、`node_modules`、`.git`、`.svn` 不会拷贝。
4. 重启/重新执行 `cyzn list` 即可看到新模板，无需修改任何代码。

### 模板继承

子模板的 `meta.json` 设置 `"extends": "template"` 后，会先渲染 `template`，再用子模板覆盖同名文件，只写差异部分。

> 当前仓库只提供 `template` 一个模板，但 CLI 的「扫描目录动态注册命令 + `extends` 继承」能力完整保留，后续新增模板无需改动任何代码。

## 模板内容约定

模板只提供**最小可运行骨架**（能 `npm start` 起来即可）。通用方法（请求拦截器、`useTable`、权限组件等）统一用 `// TODO: 按公司规范补充` 标注，由使用方按公司规范补齐。

## SVN 说明

- 生成的项目不含 `.git` 目录。
- 每个模板都带 `svn-ignore.txt`（`node_modules`、`build`、`.env.local`、`*.log` 等）。
- `package.json` 中已内置脚本：

  ```bash
  npm run svn:ignore
  # 等价于 svn propset svn:ignore -F svn-ignore.txt .
  ```

- 首次提交前请执行一次 `npm run svn:ignore`。CLI 在创建项目时若检测到当前处于 SVN 工作副本，会自动执行该命令。
- 不使用 husky，lint 通过 `npm run lint` 手动或 CI 执行。

## 发布

### 1. 登录

```bash
npm login
npm whoami        # 确认已登录
```

推公司私有源时指定 registry：

```bash
npm login --registry=http://your-nexus/repository/npm-hosted/
```

### 2. 确认包名可用

```bash
npm view cyzn
```

返回 404 表示未被占用，可以发布。

### 3. 发布预检（推荐）

```bash
npm pack --dry-run
```

重点确认：

- 输出里能看到 `templates/template/` 下的全部文件，特别是 `package.json.ejs`
- 点文件 `templates/template/.env`、`.prettierrc.cjs`、`.prettierignore` 都在（npm 不会自动排除它们，但被忽略过一次就很难查）
- `templates/` 里没有混进 `node_modules`

也可以打成本地包先装一遍验证：

```bash
npm pack                                  # 生成 cyzn-1.0.0.tgz
npm i -g ./cyzn-1.0.0.tgz                 # 全局安装本地包
cyzn list                                 # 在新目录里执行，确认模板可用
npm uninstall -g cyzn
```

### 4. 发布

```bash
npm publish
```

推私有源时：

```bash
npm publish --registry=http://your-nexus/repository/npm-hosted/
```

若希望永久写死源，可固定到 `package.json`：

```json
{
  "publishConfig": {
    "registry": "http://your-nexus/repository/npm-hosted/"
  }
}
```

### 5. 验证

```bash
npm view cyzn version
npm i -g cyzn
cyzn list
```

### 6. 后续更新

改了模板或代码后，先升版本再发布：

```bash
npm version patch     # 1.0.0 -> 1.0.1，修 bug
npm version minor     # 1.0.0 -> 1.1.0，加模板
npm version major     # 1.0.0 -> 2.0.0，不兼容变更
npm publish
```

### 注意事项

- `package.json` 的 `files` 必须包含 `templates`，否则发布后模板会丢失。
- 模板目录名 = 命令名，发布后新增模板需要重新发版，无法热更新。
- `templates/template/package-lock.json` 约 878 KB，占包体积大部分。保留可让新项目依赖版本更稳定、安装更快；若不需要，可从模板中移除，由使用者 `npm install` 自行生成。
- 不建议把模板内的 `node_modules` 提交到仓库，npm 虽会排除它，但会让 `npm pack` 变慢。