caz
v2.0.0
Published
A simple yet powerful template-based Scaffolding tools.
Downloads
2,367
Maintainers
zceReadme
简体中文 | English
简介
CAZ (Create App Zen)
这是一个基于模板机制、简单而强大的脚手架工具，用于提升我个人生产力，受启发于 Yeoman、Vue CLI 2 等项目。
- 读作：[kæz] 📷 ✌
- 写作：CAZ / caz
更多介绍，请阅读它如何工作。
特性
- 简单易用
- 轻量化
- 依然强大
- 高工作效率
- 零生产依赖
- 基于模板
- 可配置
- 可扩展
- 使用 TypeScript
- 使用现代化的 API
稍后我会给出具体的理由。
目录
起步
环境准备
安装
# 全局安装
$ npm install -g caz
# 或者使用 yarn 安装
$ yarn global add caz快速起步
使用模板创建一个新项目。
$ caz <template> [project] [-f|--force] [-o|--offline]
# 使用官方模板
$ caz <template> [project]
# 使用 GitHub 仓库（自定义模板）
$ caz <owner>/<repo> [project]如果您只是偶尔使用它，我建议您使用 npx 直接运行 caz。
$ npx caz <template> [project] [-f|--force] [-o|--offline]选项
-f, --force: 如果目标存在就覆盖掉-o, --offline: 尝试使用本地离线缓存模板
配方
GitHub 仓库模板
$ caz nm my-project此命令会从 caz-templates/nm 拉取模板，然后根据模板的配置，询问你一些问题，最后生成项目在 ./my-project。
$ caz nm#typescript my-project运行此命令，CAZ 将从 caz-templates/nm 的 typescript 分支拉取模板。
使用自定义模板
$ caz zce/nm my-project此命令会从 zce/nm 拉取模板。这意味着你也可以从你的公开 GitHub 仓库拉取模板。
注意：模板必须使用公开的仓库。
本地模板
你也可以使用本地文件系统的模板。
例如：
$ caz ~/local/template my-project以上命令将使用 ~/local/template 文件夹作为模板。
远程压缩包模板
你也可以使用 zip 压缩包的模板。
例如：
$ caz https://cdn.zce.me/boilerplate.zip my-project以上命令将从 https://cdn.zce.me/boilerplate.zip 下载并解压模板。
离线模式
$ caz nm my-project --offline运行以上命令，CAZ 将尝试从缓存中找到 nm 模板，如果找不到该模板的缓存，它仍将自动从 GitHub 下载。
命令行参数
CAZ 允许你通过命令行参数来指定提示问题的答案。
$ caz minima my-project --name my-proj运行以上命令，你就不用再回答接下来 name 的问题了。
调试模式
$ caz nm my-project --debug--debug 参数将打开调试模式。
在调试模式下，一旦发生异常，命令行将自动输出异常详细信息。这对于查找模板中的错误非常有帮助。
列出可用模版
显示全部可用的模板：
$ caz list [owner] [-j|--json] [-s|--short]参数
[owner]: GitHub 组织或用户的别名, 默认值：'caz-templates'
选项
-j, --json: 以 JSON 格式输出-s, --short: 以精简格式输出
官方模板
目前 CAZ 可用的官方模板有：
- template - 用来创建 CAZ 的模板
- nm - 用来创建 Node 模块
- vercel - 用来创建 Vercel 应用
- react - 用来创建现代化 React 应用
- vue - 用来创建现代化 Vue.js 应用
- vite - 用来创建基于 Vite 的 Vue.js 应用
- electron - :construction: 用来创建 Electron 应用
- mp - :construction: 用来创建微信小程序
- jekyll - :construction: 用来创建 Jekyll 站点
- x-pages - 用来创建 X-Pages 静态站点
可能还有更多：https://github.com/caz-templates
你也可以通过运行
$ caz list命令来实时列出所有官方模板。
目前所有模板都托管在 GitHub 上，中国用户可以使用在 coding.net 上镜像。
高级
配置选项
CAZ 将会读取 ~/.cazrc 配置文件，默认配置：
; 模板下载地址
; {owner} & {name} & {branch} 最终将被相应的值替换。
registry = https://github.com/{owner}/{name}/archive/{branch}.zip
; 模板缺省 owner 的值，可以理解为官方名称
official = caz-templates
; 缺省的模板分支名称
branch = master这就意味着你可以通过修改配置文件来自定义配置。
例如，你的 ~/.cazrc：
registry = https://gitlab.com/{owner}/{name}/archive/{branch}.zip
official = faker
branch = main然后运行以下命令：
$ caz nm my-project这样就会从 https://gitlab.com/faker/nm/archive/main.zip 下载模板。
中国用户镜像
由于网络限制，很多时候下载 GitHub 上的模板都会超时，你可以考虑使用我在 coding.net 上镜像的模板。
~/.cazrc:
registry = https://zce.coding.net/p/{owner}/d/{name}/git/archive/{branch}
official = caz请求代理
CAZ 支持网络请求代理配置。
~/.cazrc:
proxy = socks5://127.0.0.1:1080或者在使用环境变量:
$ ALL_PROXY=socks5://127.0.0.1:1080 caz nm my-project创建你的模板
$ caz template my-template以上命令会从 caz-templates/template 下载模板，并帮你创建你自己的 CAZ 模板。
创建并发布模板，详细可以请参考 如何创建模板。
也许 fork 一个官方模板是一个更好的决定。
创建你的脚手架
# 本地安装 caz 模块
$ npm install caz
# 或者使用 yarn 安装
$ yarn add caz以 ESM 和 async/await 的方式使用：
import caz from 'caz'
try {
const template = 'nm'
// project path (relative cwd or full path)
const project = 'my-project'
const options = { force: false, offline: false }
// scaffolding by caz...
await caz(template, project, options)
// success created my-project by nm template
} catch (e) {
// error handling
console.error(e)
}或者使用 CommonJS 和 Promise 的方式：
const { default: caz } = require('caz')
const template = 'nm'
// project path (relative cwd or full path)
const project = 'my-project'
const options = { force: false, offline: false }
// scaffolding by caz...
caz(template, project, options)
.then(() => {
// success created my-project by nm template
})
.catch(e => {
// error handling
console.error(e)
})这也就意味着你可以基于 CAZ 模块开发自己的脚手架工具。
创建并发布脚手架工具，详细可以请参考 如何创建脚手架工具。
参考资料
caz(template, project?, options?)
使用指定模板创建一个新项目
template
- 类型：
string - 描述：模板名称，也可以是模板文件夹路径
project
- 类型：
string - 描述：项目名称，也可以是项目文件夹路径
- 默认值：
'.'
options
- 类型：
object - 描述：选项参数 & 预设询问结果
- 默认值：
{}
force
- 类型：
boolean - 描述：如果目标路径已存在就强制覆盖
- 默认值：
false
offline
- 类型：
boolean - 描述：尝试使用离线模板
- 默认值：
false
[key: string]
- 类型：
any - 描述：命令行参数覆盖问题答案
开发动机
👉 🛠 ⚙
开个玩笑：我就是想造个轮子 ;P
真实的原因是因为我觉得我需要一个更适合我的个人生产力的脚手架工具：简洁、强大、高效。现存的工具因为出发点的不同，都或多或少有一定的局限性。
再无其他
概念
如何工作
P.S. 图片来自互联网，但是我没有记住具体来源，这里对愿作者说声抱歉。
主要的工作流程
以下中间件将按顺序依次执行：
- confirm - 使用 prompts 确认目标路径可用。
- resolve - 从远程或者本地磁盘中找到模板。
- load - 自动安装模板依赖项，使用
require加载模板的配置文件。 - inquire - 使用 prompts 询问用户模板所需要的问题。
- setup - 只是调用模板中定义的
setup钩子函数。 - prepare - 过滤掉不需要的文件，并读取全部将要输出的文件内容。
- rename - 如果文件名中包含插值表达式就重命名文件（替换文件名中的变量）。
- render - 如果文件是一个模板文件就渲染文件内容（替换文件内容中的变量）。
- emit - 将每一个文件内容输出写入到目标路径。
- install - 如果需要的话，执行
npm | yarn | pnpm install。 - init - 如果需要的话，执行
git init && git add && git commit。 - complete - 只是调用模板中定义的
complete钩子函数。
用到什么
- adm-zip - 一个 JavaScript 实现的 zip 文件压缩解压缩的库，支持内存和磁盘上的压缩解压缩。
- cac - 简单而强大的命令行工具框架。
- env-paths - 获取系统存储路径，例如数据、配置、缓存等。
- fast-glob - 非常快的和非常高效的 glob 库，用于 Node.js
- ini - 一个 Node.js 的 ini 文件解析器。
- lodash - Lodash 工具库。
- node-fetch - 一个 Node.js 的 fetch API 的封装。
- ora - 强大的终端加载动画。
- prompts - 轻量级，美观的和用户友好的提示。
- semver - 一个 Node.js 的 semver 库。
- validate-npm-package-name - 一个 Node.js 的 npm 包名验证器。
路线图
以下是我想要实现或者正在开发的功能：
- [ ] config 命令
- [ ] cache 命令
- [ ] 全部生命周期钩子
- [ ] 静默控制台输出 & 彩色控制台输出
- [ ] 越来越多的官方模板
也可以查看 打开的 Issues 中有关建议功能（和已知问题）的列表。
参与贡献
- Fork 一个仓库在 GitHub 上!
- Clone 你复刻的仓库到你本地机器上
- Checkout 一个特性分支：
git checkout -b my-awesome-feature - Commit 你的修改到你自己的分支上：
git commit -am 'Add some feature' - Push 你的修改到你复刻的仓库中：
git push -u origin my-awesome-feature - 提交一个 Pull Request 让我可以看到你的修改
提示: 请确保尝试合并你的修改之前已经拉取了上游最新的代码。