nodestack-cli
v0.0.1
Published
CLI for generating Node fullstack project templates.
Maintainers
Readme
temp-generator
一个用于生成 Node 全栈项目模板的 CLI 脚手架。
当前第一版已支持:
- 生成
monorepo项目 - 生成单独前端项目
- 生成单独后端项目
- 从本地 JSON 模板生成项目
- 在已有 monorepo 中追加
app或package init交互式问答- 交互式问答基于
inquirer - 生成项目默认使用 TypeScript
- 全栈模板自带前后端联调测试页面和 smoke test 脚本
- Nest 后端模板支持模块化能力装配
- 根据 OpenAPI / Swagger 生成前端 TypeScript SDK
当前 CLI 命令名:
create-node-stackcns
命名说明
当前仓库名是:
temp-generator这是开发期仓库名,方便先把脚手架能力做出来。
当前 CLI 对外命令名是:
create-node-stack短命令别名是:
cns当前 package.json 包名现在是:
nodestack-cli现阶段建议保留:
- 仓库名:
temp-generator - CLI 名:
create-node-stack - 短别名:
cns - npm 包名:
nodestack-cli
目录结构
.
├── docs/
│ └── planning/
├── examples/
├── src/
├── templates/
├── dist/
├── package.json
└── README.md说明:
- docs/planning 存放前期规划文档
- examples 存放 JSON 模板示例
- src 存放 CLI 源码
- templates 存放内置项目模板
- dist 是构建产物
规划文档
环境要求
- Node.js
>= 20 - pnpm
>= 10
安装依赖
pnpm install开发流程
先做类型检查:
pnpm run check构建 CLI:
pnpm run build持续编译:
pnpm run build:watch本地开发调试
当前推荐的调试方式是“先编译,再执行 dist”,因为项目现在走的是 TypeScript 编译产物运行,而不是直接执行源码。
先构建:
pnpm run build然后执行 CLI:
node dist/index.js init demo-app --template monorepo --frontend vue --frontend-name fe --backend nest --backend-name be如果不传 --template,会进入交互式问答:
node dist/index.js init demo-app或者读取 JSON 模板:
node dist/index.js init --config examples/project.template.json在已有 monorepo 中追加 app:
node /absolute/path/to/dist/index.js add app admin --frontend react在已有 monorepo 中追加 package:
node /absolute/path/to/dist/index.js add package sdk --kind generic说明:
- 当你在“生成出来的项目目录”里执行
add命令时,要指向本仓库构建后的 CLI 路径 - 因为当前你运行的是这个脚手架仓库自己的
dist/index.js - monorepo 模式下前后端目录默认名分别是
fe和be - 交互式初始化时可以自定义这两个目录名
- 生成出的全栈模板默认提供后端
/health和/test接口 - 生成出的前端模板默认提供一个“Test Backend Connection”测试页面
打包后的使用方式
方式 1:直接用构建产物执行
pnpm run build
node dist/index.js init my-app --template monorepo --frontend vue --backend nest方式 2:本地 link 成全局命令
先构建:
pnpm run build然后执行:
export PNPM_HOME="$HOME/Library/pnpm"
export PATH="$PNPM_HOME:$PATH"如果你已经把这两行写进了 ~/.zshrc,则执行:
source ~/.zshrc然后回到项目目录执行:
pnpm run build
pnpm link --globallink 完成后即可直接使用:
create-node-stack init my-app --template monorepo --frontend vue --backend nest
create-node-stack init --config ./project.template.json
cns add app admin --frontend react方式 3:发布到 npm 后使用
当前已经补好了 npm 发布所需的基础配置,发布后预期用法会是:
pnpm dlx nodestack-cli init my-app或者:
npm install -g nodestack-cli
cns init my-appnpm 发布流程
当前推荐使用 changesets + GitHub Actions 管理版本和发布,而不是长期依赖本地手工改版本。
发布前建议先确认:
- 已登录 npm:
npm whoami - 你的账号拥有该包名的发布权限
- 需要的话先把 package.json 里的
license从UNLICENSED改成最终许可证 - 如果启用自动发布,需要在 GitHub 仓库中配置
NPM_TOKENsecret
推荐流程:
- 开发改动并提交
- 执行
pnpm changeset - 把生成的
.changeset/*.md一起提交到 PR - PR 合并到
main release.yml自动创建版本 PR 或直接发布到 npm
本地生成 changeset:
pnpm changeset发布步骤:
pnpm install
pnpm run check
pnpm run build
npm publish --access public也可以直接使用内置脚本:
pnpm run publish:public版本管理脚本:
pnpm run release:patch
pnpm run release:minor
pnpm run release:major说明:
prepublishOnly会在发布前自动执行check和build- 当前 npm 包只会发布
dist、templates和README.md - GitHub Actions 工作流位于 ci.yml 和 release.yml
- 如果
nodestack-cli这个包名在 npm 上已被占用或被策略拦截,需要在 package.json 中改名后再发布
当前支持的命令
初始化项目:
create-node-stack init <project-name> [--template monorepo|frontend|nest]如果不传 --template,会进入交互流程,默认先询问:
- 创建全栈 monorepo、前端项目,还是后端项目
- 如果是前端,选择
vue或react - 如果是后端,当前固定为
nest - 如果是全栈 monorepo,默认前后端 app 目录分别为
fe和be,也可自定义
也支持显式指定 monorepo 下的 app 目录名:
create-node-stack init my-app --template monorepo --frontend vue --frontend-name fe --backend nest --backend-name be也支持显式指定部分后端能力:
create-node-stack init my-app --template monorepo --frontend react --frontend-name fe --backend nest --backend-name be --jwt --orm prisma --database postgres
create-node-stack init my-app --template monorepo --frontend react --frontend-name fe --backend nest --backend-name be --orm drizzle --database mysql按 JSON 模板初始化:
create-node-stack init --config ./project.template.json追加 app:
create-node-stack add app <name> [--frontend vue|react]
create-node-stack add app <name> --backend nest追加 package:
create-node-stack add package <name> [--kind types|utils|generic]生成前端 API SDK:
create-node-stack api generate [--openapi <path|url>] [--target <app>] [--transport fetch|axios]说明:
--openapi可传本地 JSON 文件路径或远程 URL--transport默认是fetch- monorepo 下默认会把代码生成到第一个前端 app 的
src/api - monorepo 且未传
--openapi时,默认尝试读取http://localhost:3000/docs-json axios模式下会自动给目标前端package.json补充axios依赖- 当前已支持常见 DTO 组合类型映射:
allOf、oneOf、anyOf、nullable、数组、枚举、对象交叉组合
示例:
create-node-stack api generate --openapi ./examples/openapi.sample.json
create-node-stack api generate --openapi http://localhost:3000/docs-json --target fe --transport axios生成结果结构:
src/api/
core/
client.ts
config.ts
interceptors.ts
generated/
schemas.ts
sdk.ts
index.ts生成后的前端模板默认也会带一个脚本:
pnpm api:generate如果当前项目是 monorepo,建议在前端 app 目录下执行;如果是单前端项目,直接在项目根目录执行即可。
JSON 模板示例
示例文件:
用法:
create-node-stack init --config ./examples/project.template.json当前实现状态
当前已经完成并验证:
initinit --configadd appadd packageinquirer交互式问答- TypeScript 默认模板生成
- NestJS 后端骨架模板
- 全栈模板 smoke test
- Nest 后端模块化能力装配
- Nest 后端支持 Prisma / Drizzle ORM
api generate
当前还没有完成:
- 自动安装依赖
- 自动初始化 git
doctor命令
全栈模板即时测试
当你生成的是全栈 monorepo 模板时,默认会包含:
- 后端测试接口:
GET /health - 后端测试接口:
GET /test - 前端测试按钮:页面中可直接请求后端并显示结果
- 根脚本:
pnpm test:stack
推荐测试流程:
- 安装依赖
pnpm install- 启动前后端开发环境
cd your-project
pnpm install
pnpm dev- 在另一个终端执行 smoke test
pnpm test:stack默认会请求:
http://localhost:3000/health
http://localhost:3000/test如果后端地址不是默认值,也可以这样执行:
API_BASE_URL=http://localhost:3100 pnpm test:stack