npm package: @muliminty/template-scaffold
Description: 脚手架模板仓库
Author: Muliming
Latest version: 1.0.7

# 脚手架模板仓库

一个可扩展的脚手架模板仓库，支持多技术栈（React、Vue、Next.js等）和多版本管理。

## 特性

- 🎯 **按技术栈分类**：清晰的组织结构，易于查找
- 📦 **版本管理**：每个技术栈支持多个版本/变体
- 🔧 **元数据驱动**：统一的 `template.json` 格式
- 🤖 **自动化**：脚本自动生成注册表，减少手动维护
- ✅ **类型安全**：JSON Schema 验证模板格式
- 🚀 **易于扩展**：新增模板只需遵循规范即可

## 目录结构

```
template/
├── templates/              # 所有模板的根目录
│   ├── react/             # React 技术栈
│   ├── vue/               # Vue 技术栈
│   └── next/              # Next.js 技术栈
├── .templates/            # 模板管理配置
│   ├── registry.json     # 模板注册表（自动生成）
│   ├── categories.json   # 技术栈分类配置
│   └── schema.json       # template.json 的 JSON Schema
├── scripts/               # 管理脚本
│   ├── generate-registry.js
│   ├── validate-templates.js
│   └── scaffold.js
└── docs/                  # 文档
```

## 快速开始

### 方式一：使用 npx（推荐）

如果已发布到 npm，可以直接使用：

```bash
# 查看可用模板
npx @muliminty/template-scaffold list

# 创建项目
npx @muliminty/template-scaffold create <template-id> <project-name> [project-path]
```

**注意**：
- 由于这是作用域包，必须使用完整的作用域包名 `@muliminty/template-scaffold`
- 使用单个 bin 配置，可以直接运行 `npx @muliminty/template-scaffold`，无需额外的 `-p` 参数

### 方式二：本地开发使用

在模板仓库目录内：

```bash
# 查看可用模板
npm run scaffold:list

# 使用模板创建项目
npm run scaffold:create <template-id> <project-name> [project-path]
```

### 方式三：安装到本地使用

#### 全局安装（推荐用于频繁使用）

将包安装到全局，可以在任何目录直接使用命令：

```bash
# 全局安装
npm install -g @muliminty/template-scaffold

# 安装后直接使用命令（注意：对于作用域包，命令名是去掉 @scope/ 后的部分）
template-scaffold list
template-scaffold create <template-id> <project-name> [project-path]


template-scaffold create next-v2-complete my-project
```

**说明**：由于使用了单个 bin 配置（`"bin": "scripts/scaffold.js"`），npm 会使用包名去掉作用域后的部分作为命令名，即 `template-scaffold`。如果希望使用完整的作用域包名，建议使用 `npx @muliminty/template-scaffold`。

**更新全局安装的包**：
```bash
npm update -g @muliminty/template-scaffold
```

**卸载全局包**：
```bash
npm uninstall -g @muliminty/template-scaffold
```

#### 本地项目安装

将包作为项目依赖安装，可以在项目的 `package.json` scripts 中使用：

```bash
# 在项目目录中安装
npm install @muliminty/template-scaffold

# 或使用 yarn
yarn add @muliminty/template-scaffold

# 或使用 pnpm
pnpm add @muliminty/template-scaffold
```

安装后，可以在 `package.json` 的 `scripts` 中使用：

```json
{
  "scripts": {
    "create:project": "template-scaffold create next-v2-complete my-project"
  }
}
```

**注意**：在 `package.json` 的 `scripts` 中使用时，如果包已安装到项目依赖中，可以直接使用 `template-scaffold` 命令名。也可以使用 `npx @muliminty/template-scaffold`。

然后运行：
```bash
npm run create:project
```

或者使用 `npx` 运行本地安装的包：
```bash
npx @muliminty/template-scaffold list
npx @muliminty/template-scaffold create <template-id> <project-name> [project-path]
```

### 方式四：使用 npx 运行本地包

在模板仓库目录外，使用 npx 运行本地包：

```bash
# 从模板仓库目录运行
npx /path/to/template/scripts/scaffold.js list
npx /path/to/template/scripts/scaffold.js create <template-id> <project-name> [project-path]
```

### 使用模板创建项目

```bash
# 使用 npx（如果已发布）
npx @muliminty/template-scaffold create <template-id> <project-name> [project-path]

# 或本地使用
npm run scaffold:create <template-id> <project-name> [project-path]
```

#### 路径处理说明

脚手架工具支持多种路径指定方式，行为与主流脚手架工具（create-next-app、create-vite）一致：

**场景 1: 在当前目录创建新文件夹（默认）**
```bash
# 使用 npx（如果已发布）
npx @muliminty/template-scaffold create next-v2-complete my-project
# 或本地使用
npm run scaffold:create next-v2-complete my-project
# 创建: ./my-project/ （在当前工作目录下）
```

**场景 2: 在当前目录直接创建（不创建子文件夹）**
```bash
# 使用 npx（如果已发布）
npx @muliminty/template-scaffold create next-v2-complete my-project .
# 或本地使用
npm run scaffold:create next-v2-complete my-project .
# 在当前目录直接创建文件
```

**场景 3: 指定相对路径**
```bash
# 使用 npx（如果已发布）
npx @muliminty/template-scaffold create next-v2-complete my-project ../my-project
# 或本地使用
npm run scaffold:create next-v2-complete my-project ../my-project
# 创建: ../my-project/ （相对于当前工作目录）
```

**场景 4: 指定绝对路径**
```bash
# 使用 npx（如果已发布）
npx @muliminty/template-scaffold create next-v2-complete my-project /Users/username/projects/my-project
# 或本地使用
npm run scaffold:create next-v2-complete my-project /Users/username/projects/my-project
# 创建: /Users/username/projects/my-project/
```

#### 使用示例

```bash
# 基本用法：在当前目录创建新项目
# 使用 npx（如果已发布）
npx @muliminty/template-scaffold create next-v2-complete my-project
# 或本地使用
npm run scaffold:create next-v2-complete my-project

# 在当前目录直接创建（不创建子文件夹）
# 使用 npx（如果已发布）
npx @muliminty/template-scaffold create next-v2-complete my-project .
# 或本地使用
npm run scaffold:create next-v2-complete my-project .

# 指定自定义路径
# 使用 npx（如果已发布）
npx @muliminty/template-scaffold create next-v2-complete my-project ~/projects/my-project
# 或本地使用
npm run scaffold:create next-v2-complete my-project ~/projects/my-project
```

#### 路径验证

脚手架会自动检查：
- 目标路径是否已存在
- 目标路径是否为文件（而非目录）
- 目标目录是否为空（如果已存在且非空，会报错）

如果目标路径已存在且非空，需要先清理或选择其他位置。

### 管理模板

```bash
# 验证所有模板
npm run validate

# 生成模板注册表
npm run generate-registry
```

## 可用模板

运行以下命令查看所有可用模板：

```bash
# 使用 npx（如果已发布）
npx @muliminty/template-scaffold list

# 或本地使用
npm run scaffold:list
```

当前支持的模板：

- **Next.js**
  - `next-v1-app-router` - Next.js App Router 全栈模板
  - `next-v2-complete` - Next.js 完整项目模板（包含开发规范配置）

## 添加新模板

1. 在 `templates/{技术栈}/` 下创建版本目录
2. 创建 `template.json` 元数据文件
3. 添加完整的项目代码
4. 运行 `npm run generate-registry` 更新注册表
5. 运行 `npm run validate` 验证模板

详细指南请参考 [模板开发指南](./docs/TEMPLATE_GUIDE.md)。

## 文档

- [架构说明](./docs/ARCHITECTURE.md) - 详细的架构设计说明
- [贡献指南](./docs/CONTRIBUTING.md) - 如何贡献新模板
- [模板开发指南](./docs/TEMPLATE_GUIDE.md) - 模板开发详细指南
- [npx 使用指南](./docs/NPX_USAGE.md) - 如何使用 npx 运行脚手架工具
- [npm 发布指南](./docs/NPM_PUBLISH.md) - 如何发布到 npm

## 命名规范

### 模板目录命名

格式：`v{版本号}-{特性描述}`

示例：
- `v1-basic` - 基础版本
- `v2-with-router` - 带路由的版本
- `v1-app-router` - App Router 版本

### 模板 ID 命名

格式：`{技术栈}-v{版本号}-{特性描述}`

示例：
- `react-v1-basic`
- `vue-v2-with-pinia`
- `next-v1-app-router`

## 模板变量

模板支持变量替换，在模板文件中使用 `{{变量名}}` 占位符：

- `{{projectName}}` - 项目名称
- `{{projectDescription}}` - 项目描述
- `{{author}}` - 作者信息
- `{{date}}` - 创建日期

在 `template.json` 的 `variables` 字段中定义自定义变量。

## 发布到 npm

如果你想通过 `npx @muliminty/template-scaffold` 使用，需要将包发布到 npm。

### 快速发布步骤

1. **修改 `package.json`**：
   - 移除或设置 `"private": false`
   - 确保包名唯一（检查：`npm view @muliminty/template-scaffold`）
   - 添加作者信息
   - 添加 `files` 字段指定要发布的文件

2. **登录 npm**：
   ```bash
   npm login
   ```

3. **发布**：
   ```bash
   npm publish --access public
   ```

4. **使用**：
   ```bash
   # 查看可用模板
   npx @muliminty/template-scaffold list
   
   # 创建项目
   npx @muliminty/template-scaffold create next-v2-complete my-project
   ```
   
   **说明**：由于使用了单个 bin 配置（`"bin": "scripts/scaffold.js"`），可以直接使用 `npx @muliminty/template-scaffold`，无需使用 `-p` 参数。这是作用域包使用 npx 的最佳实践。

详细发布指南请参考 [npm 发布指南](./docs/NPM_PUBLISH.md)。

## 开发

### 安装依赖

```bash
npm install
```

### 运行脚本

```bash
# 验证模板
npm run validate

# 生成注册表
npm run generate-registry

# 列出模板
npm run scaffold:list
# 或使用 npx（如果已发布）
npx @muliminty/template-scaffold list

# 创建项目
npm run scaffold:create <template-id> <project-name> [project-path]
# 或使用 npx（如果已发布）
npx @muliminty/template-scaffold create <template-id> <project-name> [project-path]
```

**注意**：项目会创建在当前工作目录下。建议在项目父目录运行命令，而不是在模板仓库目录内。

## 许可证

MIT