Caz NPM | npm.io

简体中文 | English

简介

CAZ (Create App Zen)

这是一个基于模板机制、简单而强大的脚手架工具，用于提升我个人生产力，受启发于 Yeoman、Vue CLI 2 等项目。

读作：[kæz] 📷 ✌
写作：CAZ / caz

更多介绍，请阅读它如何工作。

特性

简单易用
轻量化
依然强大
高工作效率
零生产依赖
基于模板
可配置
可扩展
使用 TypeScript
使用现代化的 API

稍后我会给出具体的理由。

起步

环境准备

Node.js (必须 >= 16.x, >= 18.x 更佳)
npm (>= 7.x) 或 pnpm (>= 6.x) 或 yarn (>= 1.22)
Git (>= 2.0)

安装

# 全局安装
$ 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 模块开发自己的脚手架工具。

创建并发布脚手架工具，详细可以请参考如何创建脚手架工具。