caz
    TypeScript icon, indicating that this package has built-in type declarations

    1.1.0 • Public • Published
    CAZ

    A simple yet powerful template-based Scaffolding tools for my personal productivity.

    Build Status Coverage Status License NPM Version Node Version
    Code Style NPM Downloads Install Size Repo Size Dependencies Status


    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

    Getting Started

    Prerequisites

    • Node.js (>= 14.14 required, >= 16.13 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:

    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 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)
      })

    This means that you can develop your own scaffolding module based on it.

    To create and distribute your own scaffolding tools, please refer to the How to create scaffolding tools based on CAZ.

    References

    caz(template, project?, options?)

    Create new project from a template

    template

    • Type: string
    • Details: template name, it can also be a template folder path

    project

    • Type: string
    • Details: project name, it can also be a project folder path
    • Default: '.'

    options

    • Type: object
    • Details: options & prompts override
    • Default: {}
    force
    • Type: boolean
    • Details: overwrite if the target exists
    • Default: false
    offline
    • Type: boolean
    • Details: try to use an offline template
    • Default: false
    [key: string]
    • Type: any
    • Details: cli options to override prompts

    Motivation

    👉 🛠

    Joking: I want to make wheels ;P

    The real reason is that I think I need a scaffolding tool that is more suitable for my personal productivity. The existing tools have more or less certain limitations because of their different starting points.

    Nothing else.

    Concepts

    How It Works

    Scaffolding flow

    P.S. The picture is from the Internet, but I have forgotten the specific source, sorry to the author.

    Main Workflow

    The core code is based on the middleware mechanism provided by zce/mwa.

    The following middleware will be executed sequentially.

    1. confirm - Confirm destination by prompts.
    2. resolve - Resolve template from remote or local filesystem.
    3. load - Install template dependencies, load template config by require.
    4. inquire - Inquire template prompts by prompts.
    5. setup - Only apply template setup hook function.
    6. prepare - Filter out unnecessary files and prepare all files to be generated.
    7. rename - Rename each file if the filename contains interpolations.
    8. render - Render the contents of each file if template.
    9. emit - Emit files to destination.
    10. install - Execute npm | yarn | pnpm install command if necessary.
    11. init - Execute git init && git add && git commit command if necessary.
    12. complete - Only apply template complete hook function.

    Built With

    • adm-zip - A Javascript implementation of zip for nodejs. Allows user to create or extract zip files both in memory or to/from disk
    • cac - Simple yet powerful framework for building command-line apps.
    • env-paths - Get paths for storing things like data, config, cache, etc
    • fast-glob - It's a very fast and efficient glob library for Node.js
    • ini - An ini encoder/decoder for node
    • lodash - Lodash modular utilities.
    • node-fetch - A light-weight module that brings Fetch API to node.js
    • ora - Elegant terminal spinner
    • prompts - Lightweight, beautiful and user-friendly prompts
    • semver - The semantic version parser used by npm.
    • validate-npm-package-name - Give me a string and I'll tell you if it's a valid npm package name

    Roadmap

    The following are the features I want to achieve or are under development:

    • [ ] config command
    • [ ] cache command
    • [ ] all lifecycle hooks
    • [ ] console output (colorful & verbose)
    • [ ] more and more official templates

    See the open issues for a list of proposed features (and known issues).

    Contributing

    1. Fork it on GitHub!
    2. Clone the fork to your own machine.
    3. Checkout your feature branch: git checkout -b my-awesome-feature
    4. Commit your changes to your own branch: git commit -am 'Add some feature'
    5. Push your work back up to your fork: git push -u origin my-awesome-feature
    6. Submit a Pull Request so that we can review your changes.

    NOTE: Be sure to merge the latest from "upstream" before making a pull request!

    License

    Distributed under the MIT License. See LICENSE for more information. © 汪磊

    Install

    npm i caz

    DownloadsWeekly Downloads

    224

    Version

    1.1.0

    License

    MIT

    Unpacked Size

    651 kB

    Total Files

    10

    Last publish

    Collaborators

    • zce