Caz

<div align="center"> <a href="https://github.com/zce/caz"><img src="docs/caz.png" alt="CAZ"></a> <p>A simple yet powerful template-based Scaffolding tools for my personal productivity.</p> <p> <a href="https://github.com/zce/caz/actions"><img src="https://img.shields.io/github/actions/workflow/status/zce/caz/main.yml" alt="Build Status"></a> <a href="https://codecov.io/gh/zce/caz"><img src="https://img.shields.io/codecov/c/github/zce/caz" alt="Coverage Status"></a> <a href="https://github.com/zce/caz/blob/master/LICENSE"><img src="https://img.shields.io/github/license/zce/caz" alt="License"></a> <a href="https://npm.im/caz"><img src="https://img.shields.io/npm/v/caz" alt="NPM Version"></a> <a href="https://npm.im/caz"><img src="https://img.shields.io/node/v/caz" alt="Node Version"></a> <br> <a href="https://standardjs.com"><img src="https://img.shields.io/badge/code_style-standard-brightgreen" alt="Code Style"></a> <a href="https://npm.im/caz"><img src="https://img.shields.io/npm/dm/caz" alt="NPM Downloads"></a> <a href="https://packagephobia.com/result?p=caz"><img src="https://packagephobia.com/badge?p=caz" alt="Install Size"></a> <a href="https://github.com/zce/caz"><img src="https://img.shields.io/github/repo-size/zce/caz" alt="Repo Size"></a> <a href="https://github.com/zce/caz"><img src="https://img.shields.io/librariesio/github/zce/caz" alt="Dependencies Status"></a> </p> </div> <br>

English | 简体中文

Introduction

CAZ (Create App Zen)

It's a a simple template-based Scaffolding tools for my personal productivity, inspired by Yeoman & Vue CLI 2 & etc.

• pronounced: [kæz] 📷 ✌
• written: CAZ / caz

For more introduction, please refer to the How it works.

Features

• Easy to use
• Light-weight
• Still powerful
• High efficiency
• Zero dependencies
• Template-based
• Configurable
• Extensible
• TypeScript
• Use modern API

I'll give you specific reasons later.

Table of Contents

• Introduction
  • Features
• Getting Started
  • Prerequisites
  • Installation
  • Quick Start
• Recipes
  • GitHub Repo Templates
  • Local Templates
  • Remote ZIP Templates
  • Offline Mode
  • Prompts Override
  • Debug Mode
  • List Available Templates
• Official Templates
• Advanced
  • Configuration
  • Create Your Template
  • Create Your Scaffold
• References
• Motivation
• About
  • How It Works
  • Built With
• Roadmap
• Contributing
• License

Getting Started

Prerequisites

• Node.js (>= 16.x required, >= 18.x preferred)
• npm (>= 7.x) or pnpm (>= 6.x) or yarn (>= 1.22)
• Git (>= 2.0)

Installation

# install it globally
$ npm install -g caz

# or yarn
$ yarn global add caz

Quick Start

Create new project from a template.

$ caz <template> [project] [-f|--force] [-o|--offline]

# caz with an official template
$ caz <template> [project]

# caz with a github repo
$ caz <owner>/<repo> [project]

If you only use it occasionally, I recommend that you use npx to run caz directly.

$ npx caz <template> [project] [-f|--force] [-o|--offline]

Options

• -f, --force: Overwrite if the target exists
• -o, --offline: Try to use an offline template

Recipes

GitHub Repo Templates

$ caz nm my-project

The above command pulls the template from caz-templates/nm, then prompts for some information according to the configuration of this template, and generate the project at ./my-project.

$ caz nm#typescript my-project

By running this command, CAZ will pulls the template from typescript branch of caz-templates/nm.

Use Custom templates

$ caz zce/nm my-project

The above command pulls the template from zce/nm. This means that you can also pull templates from your public GitHub repository.

Public repository is necessary.

Local Templates

Instead of a GitHub repo, you can also use a template on your local file system.

e.g.

$ caz ~/local/template my-project

The above command use the template from ~/local/template.

Remote ZIP Templates

Instead of a GitHub repo, you can also use a template with a zip file uri.

e.g.

$ caz https://cdn.zce.me/boilerplate.zip my-project

The above command will download & extract template from https://cdn.zce.me/boilerplate.zip.

Offline Mode

$ caz nm my-project --offline

By running this command, CAZ will try to find a cached version of nm template or download from GitHub if it's not yet cached.

Prompts Override

CAZ allows you to specify prompt response answers through cli parameters.

$ caz minima my-project --name my-proj

By running this command, you don't have to answer the next name prompts.

Debug Mode

$ caz nm my-project --debug

--debug parameter will open the debug mode.

In debug mode, once an exception occurs, the exception details will be automatically output. This is very helpful in finding errors in the template.

List Available Templates

Show all available templates:

$ caz list [owner] [-j|--json] [-s|--short]

Arguments

• [owner]: GitHub orgs or user slug, default: 'caz-templates'

Options

• -j, --json: Output with json format
• -s, --short: Output with short format

Official Templates

Current available templates list:

• template - for creating caz templates.
• nm - for creating node modules.
• vercel - for creating vercel apps.
• react - for creating modern react apps.
• vue - for creating modern vue.js apps.
• vite - for creating vue.js apps powered by vite.
• electron - :construction: for creating electron apps.
• mp - :construction: for creating wechat mini-programs.
• jekyll - :construction: for creating jekyll site.
• x-pages - for creating x-pages static site.

Maybe more: https://github.com/caz-templates

You can also run $ caz list to see all available official templates in real time.

All templates are currently hosted on GitHub, Chinese users can use the mirror on coding.net.

Advanced

Configuration

CAZ will read the configuration file in ~/.cazrc, default config:

; template download registry
; {owner} & {name} & {branch} will eventually be replaced by the corresponding value.
registry = https://github.com/{owner}/{name}/archive/{branch}.zip
; template offlicial organization name
official = caz-templates
; default template branch name
branch = master

This means that you can customize the configuration by modifying the configuration file.

For example, in your ~/.cazrc:

registry = https://gitlab.com/{owner}/{name}/archive/{branch}.zip
official = faker
branch = main

Then run the following command:

$ caz nm my-project

The above command will download & extract template from https://gitlab.com/faker/nm/archive/main.zip.

Mirror for Chinese

Due to network limitations, the template download may time out, you can consider using the mirror repository I configured on coding.net.

~/.cazrc:

registry = https://zce.coding.net/p/{owner}/d/{name}/git/archive/{branch}
official = caz

Socks Proxy

CAZ supports socks proxy config.

~/.cazrc:

proxy = socks5://127.0.0.1:1080

or environment variable:

$ ALL_PROXY=socks5://127.0.0.1:1080 caz nm my-project

Create Your Template

$ caz template my-template

The above command will pulls the template from caz-templates/template, and help you create your own CAZ template.

To create and distribute your own template, please refer to the How to create template.

Maybe fork an official template is also a good decision.

Create Your Scaffold

# install it locally
$ npm install caz

# or yarn
$ yarn add caz

with ESM and 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)
}

or with CommonJS and Promise:

const { default: caz } = require('caz')

const template = 'nm'
// project pa