diff --git a/.github/contributing.md b/.github/contributing.md index ee421c4f..0bcb2c32 100644 --- a/.github/contributing.md +++ b/.github/contributing.md @@ -11,8 +11,9 @@ ## Prerequisites -- [Node.js](https://nodejs.org) (>= 14.17) -- [npm](https://www.npmjs.com) (>= 6.14) +- [Node.js](https://nodejs.org) (>= 16.13) +- [npm](https://www.npmjs.com) (>= 7.x) +- [pnpm](https://pnpm.io) (>= 6.x) - [yarn](https://yarnpkg.com) (>= 1.22) - [Git](https://git-scm.com) (>= 2.20) @@ -22,6 +23,7 @@ $ git clone https://github.com/zce/caz.git $ cd caz $ npm install +$ npm run build $ npm link ``` diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index c0783ab3..d37c07bc 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -5,30 +5,21 @@ on: [push, pull_request] jobs: build: runs-on: ubuntu-latest - strategy: matrix: - node-version: [12, 14, 16] - + node-version: [14, 16, 17] steps: - - uses: actions/checkout@v2 - - uses: actions/setup-node@v2 + - uses: actions/checkout@v3 + - uses: actions/setup-node@v3 with: node-version: ${{ matrix.node-version }} + - run: npm i pnpm yarn -g + - run: git config --global user.name "GitHub Actions" + - run: git config --global user.email "bots@github.com" - run: npm install - run: npm run lint - run: npm run build - run: npm run test - - codecov: - if: github.ref == 'refs/heads/main' - needs: build - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v2 - - uses: actions/setup-node@v2 - - run: npm install - - run: npm run test - run: npx codecov publish: @@ -36,8 +27,8 @@ jobs: needs: build runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 - - uses: actions/setup-node@v2 + - uses: actions/checkout@v3 + - uses: actions/setup-node@v3 with: registry-url: https://registry.npmjs.org - run: npm install diff --git a/.gitignore b/.gitignore index fe01137e..96a9b15b 100644 --- a/.gitignore +++ b/.gitignore @@ -2,10 +2,11 @@ node_modules -/lib +/dist /coverage /test/.temp package-lock.json +pnpm-lock.yaml yarn.lock diff --git a/CHANGELOG.md b/CHANGELOG.md index 954b665a..b751d6a3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,17 @@ # Changelog +## [1.0.0] - 2022-03-24 + +- zero dependency by tsup +- node v14.14.0 required +- auto install template dependencies +- support native esm +- upgrade all dependencies +- refactor test +- chore: minify output dist +- docs: chinese docs +- fix: dts output + ## [0.8.2] - 2022-01-20 - fix: output types.d.ts @@ -84,6 +96,7 @@ +[1.0.0]: https://github.com/zce/caz/compare/v0.8.2...v1.0.0 [0.8.2]: https://github.com/zce/caz/compare/v0.8.1...v0.8.2 [0.8.1]: https://github.com/zce/caz/compare/v0.8.0...v0.8.1 [0.8.0]: https://github.com/zce/caz/compare/v0.7.0...v0.8.0 diff --git a/README.md b/README.md index 55a529e2..df59b5a2 100644 --- a/README.md +++ b/README.md @@ -7,18 +7,19 @@ License NPM Version Node Version - Code Style
+ Code Style NPM Downloads Install Size - Repo size - Dependencies Status - DevDependencies Status + Repo Size + Dependencies Status


+**English** | [简体中文](README.zh-CN.md) + ## Introduction CAZ (**C**reate **A**pp **Z**en) @@ -36,7 +37,7 @@ _For more introduction, please refer to the [How it works](#how-it-works)._ - Light-weight - Still powerful - High efficiency -- Less dependencies +- Zero dependencies - Template-based - Configurable - Extensible @@ -58,11 +59,13 @@ _For more introduction, please refer to the [How it works](#how-it-works)._ - [Local Templates](#local-templates) - [Remote ZIP Templates](#remote-zip-templates) - [Offline Mode](#offline-mode) + - [Prompts Override](#prompts-override) + - [Debug Mode](#debug-mode) - [List Available Templates](#list-available-templates) - - [Official Templates](#official-templates) +- [Official Templates](#official-templates) - [Advanced](#advanced) - - [Create Your Template](#create-your-template) - [Configuration](#configuration) + - [Create Your Template](#create-your-template) - [Create Your Scaffold](#create-your-scaffold) - [References](#references) - [Motivation](#motivation) @@ -77,8 +80,8 @@ _For more introduction, please refer to the [How it works](#how-it-works)._ ### Prerequisites -- [Node.js](https://nodejs.org) (>= 12.10 required, >= 14.17 preferred) -- [npm](https://www.npmjs.com) (>= 6.x) or [yarn](https://yarnpkg.com) (>= 1.22) +- [Node.js](https://nodejs.org) (>= 14.14 required, >= 16.13 preferred) +- [npm](https://www.npmjs.com) (>= 7.x) or [pnpm](https://pnpm.io) (>= 6.x) or [yarn](https://yarnpkg.com) (>= 1.22) - [Git](https://git-scm.com) (>= 2.0) ### Installation @@ -182,17 +185,21 @@ 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 ```shell $ 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. +`--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 +Show all available templates: ```shell $ caz list [owner] [-j|--json] [-s|--short] @@ -207,16 +214,17 @@ $ caz list [owner] [-j|--json] [-s|--short] - `-j, --json`: Output with json format - `-s, --short`: Output with short format -### Official Templates +## Official Templates Current available templates list: - [template](https://github.com/caz-templates/template) - for creating [caz](https://github.com/zce/caz) templates. - [nm](https://github.com/caz-templates/nm) - for creating [node](https://nodejs.org) modules. -- [react](https://github.com/caz-templates/react) - for creating modern [react](https://reactjs.org) app. -- [vue](https://github.com/caz-templates/vue) - for creating modern [vue.js](https://vuejs.org) app. -- [vite](https://github.com/caz-templates/vite) - for creating vue.js app powered by [vite](https://github.com/vitejs/vite). -- [electron](https://github.com/caz-templates/electron) - :construction: for creating [electron](https://electronjs.org) app. +- [vercel](https://github.com/caz-templates/vercel) - for creating [vercel](https://vercel.com) apps. +- [react](https://github.com/caz-templates/react) - for creating modern [react](https://reactjs.org) apps. +- [vue](https://github.com/caz-templates/vue) - for creating modern [vue.js](https://vuejs.org) apps. +- [vite](https://github.com/caz-templates/vite) - for creating vue.js apps powered by [vite](https://github.com/vitejs/vite). +- [electron](https://github.com/caz-templates/electron) - :construction: for creating [electron](https://electronjs.org) apps. - [mp](https://github.com/caz-templates/mp) - :construction: for creating wechat [mini-programs](https://developers.weixin.qq.com/miniprogram/dev/framework). - [jekyll](https://github.com/caz-templates/jekyll) - :construction: for creating [jekyll](https://jekyllrb.com) site. - [x-pages](https://github.com/caz-templates/x-pages) - for creating [x-pages](https://github.com/zce/x-pages) static site. @@ -225,26 +233,16 @@ Maybe more: https://github.com/caz-templates > You can also run `$ caz list` to see all available official templates in real time. -## Advanced - -### Create Your Template - -```shell -$ caz template my-template -``` +**All templates are currently hosted on GitHub, Chinese users can [use the mirror](#mirror-for-chinese) on coding.net.** -The above command will pulls the template from [caz-templates/template](https://github.com/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](docs/create-template.md). - -> Maybe fork an official template is also a good decision. +## Advanced ### Configuration CAZ will read the configuration file in `~/.cazrc`, default config: ```ini -; template download registry, +; 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 @@ -271,6 +269,29 @@ $ 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](https://coding.net). + +`~/.cazrc`: + +```ini +registry = https://zce.coding.net/p/{owner}/d/{name}/git/archive/{branch} +official = caz +``` + +### Create Your Template + +```shell +$ caz template my-template +``` + +The above command will pulls the template from [caz-templates/template](https://github.com/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](docs/create-template.md). + +> Maybe fork an official template is also a good decision. + ### Create Your Scaffold ```shell @@ -286,20 +307,18 @@ with ESM and async/await: ```javascript import caz from 'caz' -;(async () => { - 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) - } -})() +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: @@ -326,8 +345,6 @@ 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](docs/create-scaffold.md). - - ## References @@ -339,12 +356,12 @@ Create new project from a template #### template - Type: `string` -- Details: template name +- Details: template name, it can also be a template folder path #### project - Type: `string` -- Details: project name +- Details: project name, it can also be a project folder path - Default: `'.'` #### options @@ -355,20 +372,20 @@ Create new project from a template ##### force -Type: `boolean` -Details: overwrite if the target exists -Default: `false` +- Type: `boolean` +- Details: overwrite if the target exists +- Default: `false` ##### offline -Type: `boolean` -Details: try to use an offline template -Default: `false` +- Type: `boolean` +- Details: try to use an offline template +- Default: `false` ##### [key: string] -Type: `any` -Details: cli options to override prompts +- Type: `any` +- Details: cli options to override prompts ## Motivation @@ -376,13 +393,11 @@ Details: cli options to override prompts 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 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. - - -## About +## Concepts ### How It Works @@ -392,22 +407,22 @@ Nothing else. #### Main Workflow -The [core code](src/init/index.ts) is based on the middleware mechanism provided by [zce/mwa](https://github.com/zce/mwa). +The [core code](src/index.ts) is based on the middleware mechanism provided by [zce/mwa](https://github.com/zce/mwa). The following middleware will be executed sequentially. -1. [confirm](src/init/confirm.ts) - Confirm destination by [prompts](https://github.com/terkelg/prompts). -2. [resolve](src/init/resolve.ts) - Resolve template from remote or local. -3. [load](src/init/load.ts) - Load template config by require. -4. [inquire](src/init/inquire.ts) - Inquire template prompts by [prompts](https://github.com/terkelg/prompts). -5. [setup](src/init/setup.ts) - Apply template setup hook. -6. [prepare](src/init/prepare.ts) - Prepare all template files. -7. [rename](src/init/rename.ts) - Rename file if necessary. -8. [render](src/init/render.ts) - Render file if template. -9. [emit](src/init/emit.ts) - Emit files to destination. -10. [install](src/init/install.ts) - Execute `npm | yarn | pnpm install` command. -11. [init](src/init/init.ts) - Execute `git init && git add && git commit` command. -12. [complete](src/init/complete.ts) - Apply template complete hook. +1. [confirm](src/confirm.ts) - Confirm destination by [prompts](https://github.com/terkelg/prompts). +2. [resolve](src/resolve.ts) - Resolve template from remote or local filesystem. +3. [load](src/load.ts) - Install template dependencies, load template config by `require`. +4. [inquire](src/inquire.ts) - Inquire template prompts by [prompts](https://github.com/terkelg/prompts). +5. [setup](src/setup.ts) - Only apply template setup hook function. +6. [prepare](src/prepare.ts) - Filter out unnecessary files and prepare all files to be generated. +7. [rename](src/rename.ts) - Rename each file if the filename contains interpolations. +8. [render](src/render.ts) - Render the contents of each file if template. +9. [emit](src/emit.ts) - Emit files to destination. +10. [install](src/install.ts) - Execute `npm | yarn | pnpm install` command if necessary. +11. [init](src/init.ts) - Execute `git init && git add && git commit` command if necessary. +12. [complete](src/complete.ts) - Only apply template complete hook function. ### Built With diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 00000000..244dde04 --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,468 @@ +
+ CAZ +

一个基于模板机制、简单而又强大的脚手架工具，用于提升我个人生产力。

+

+ 构建状态 + 测试覆盖率 + 许可证 + NPM 版本 + Node 版本要求 +
+ 代码风格 + NPM 下载量 + 安装包体积 + 仓库体积 + 依赖状态 +

+
+ +
+ +**简体中文** | [English](README.md) + +## 简介 + +CAZ (**C**reate **A**pp **Z**en) + +这是一个基于模板机制、简单而强大的脚手架工具，用于提升我个人生产力，受启发于 [Yeoman](https://yeoman.io)、[Vue CLI 2](https://npm.im/vue-cli) 等项目。 + +- 读作：[[kæz]](http://dict.youdao.com/dictvoice?audio=caz) 📷 ✌ +- 写作：CAZ / caz + +_更多介绍，请阅读[它如何工作](#如何工作)。_ + +### 特性 + +- 简单易用 +- 轻量化 +- 依然强大 +- 高工作效率 +- 零生产依赖 +- 基于模板 +- 可配置 +- 可扩展 +- 使用 TypeScript +- 使用现代化的 API + +> 稍后我会给出具体的理由。 + +## 目录 + +- [简介](#简介) + - [特性](#特性) +- [起步](#起步) + - [环境准备](#环境准备) + - [安装](#安装) + - [快速起步](#快速起步) +- [配方](#配方) + - [GitHub 仓库模板](#gitHub-仓库模板) + - [本地模板](#本地模板) + - [远程压缩包模板](#远程压缩包模板) + - [离线模式](#离线模式) + - [命令行参数](#命令行参数) + - [调试模式](#调试模式) + - [列出可用模板](#列出可用模板) +- [官方模板](#官方模板) +- [高级](#高级) + - [配置选项](#配置选项) + - [创建你的模板](#创建你的模板) + - [创建你的脚手架](#创建你的脚手架) +- [参考资料](#参考资料) +- [开发动机](#开发动机) +- [概念](#概念) + - [如何工作](#如何工作) + - [用到什么](#用到什么) +- [路线图](#路线图) +- [参与贡献](#参与贡献) +- [许可证](#许可证) + +## 起步 + +### 环境准备 + +- [Node.js](https://nodejs.org) (必须 >= 14.14, >= 16.13 更佳) +- [npm](https://www.npmjs.com) (>= 7.x) 或 [pnpm](https://pnpm.io) (>= 6.x) 或 [yarn](https://yarnpkg.com) (>= 1.22) +- [Git](https://git-scm.com) (>= 2.0) + +### 安装 + +```shell +# 全局安装 +$ npm install -g caz + +# 或者使用 yarn 安装 +$ yarn global add caz +``` + +### 快速起步 + +使用模板创建一个新项目。 + +```shell +$ caz