AgileBuilder logoAgileBuilder
返回文档

模板系统

了解 AgileBuilder 的模板系统

什么是模板

模板是 AgileBuilder 的核心资产。它是一个包含项目结构、配置文件和代码的目录，通过变量和条件渲染，可以生成不同配置的项目。

my-template/
├── agilebuilder.json      # 模板配置文件
├── template/              # 模板文件目录
│   ├── src/
│   ├── package.json.hbs   # Handlebars 模板
│   └── README.md.hbs
└── hooks/                 # 钩子脚本（可选）
    ├── pre-generate.js
    └── post-generate.js

模板配置

agilebuilder.json 是模板的核心配置文件：

{
  "name": "react-starter",
  "version": "1.0.0",
  "description": "React 项目启动模板",
  "variables": [
    {
      "name": "projectName",
      "type": "string",
      "description": "项目名称",
      "required": true
    },
    {
      "name": "useTypeScript",
      "type": "boolean",
      "description": "是否使用 TypeScript",
      "default": true
    }
  ],
  "hooks": {
    "post-generate": [
      "@agilebuilder/install-deps",
      "@agilebuilder/git-init"
    ]
  }
}

变量系统

变量类型

类型说明示例
string字符串项目名称、包名
boolean布尔值是否启用功能
select单选选择框架
multiselect多选选择多个模块

变量定义示例

{
  "variables": [
    {
      "name": "projectName",
      "type": "string",
      "description": "项目名称",
      "required": true,
      "pattern": "^[a-z][a-z0-9-]*$"
    },
    {
      "name": "framework",
      "type": "select",
      "description": "选择框架",
      "options": ["react", "vue", "svelte"],
      "default": "react"
    },
    {
      "name": "features",
      "type": "multiselect",
      "description": "选择功能",
      "options": ["eslint", "prettier", "husky", "jest"],
      "default": ["eslint", "prettier"]
    }
  ]
}

条件渲染

使用 Handlebars 语法进行条件渲染：

{{#if useTypeScript}}
{
  "devDependencies": {
    "typescript": "^5.0.0"
  }
}
{{/if}}

unless 条件

{{#unless useJavaScript}}
此项目不使用 JavaScript
{{/unless}}

循环渲染

{{#each features}}
- {{this}}
{{/each}}

渲染结果：

- eslint
- prettier
- husky

文件名变量

文件名中也可以使用变量：

template/
├── {{projectName}}/
│   └── index.js
└── src/
    └── {{#if useTypeScript}}index.ts{{else}}index.js{{/if}}

Hooks

Hooks 让你在项目生成前后执行自动化脚本：

{
  "hooks": {
    "pre-generate": "node hooks/pre-generate.js",
    "post-generate": [
      "@agilebuilder/install-deps",
      "@agilebuilder/git-init",
      "node hooks/custom.js"
    ]
  }
}

模板管理命令

# 列出所有模板
agilebuilder template list

# 查看模板详情
agilebuilder template info <template-name>

# 添加模板
agilebuilder template add <git-url>

# 创建模板
agilebuilder template create <path> --name <template-name>

# 删除模板
agilebuilder template remove <template-name>

下一步