Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (nodestack-cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

temp-generator

一个用于生成 Node 全栈项目模板的 CLI 脚手架。

当前第一版已支持：

生成 monorepo 项目
生成单独前端项目
生成单独后端项目
从本地 JSON 模板生成项目
在已有 monorepo 中追加 app 或 package
init 交互式问答
交互式问答基于 inquirer
生成项目默认使用 TypeScript
全栈模板自带前后端联调测试页面和 smoke test 脚本
Nest 后端模板支持模块化能力装配
根据 OpenAPI / Swagger 生成前端 TypeScript SDK

当前 CLI 命令名：

create-node-stack
cns

命名说明

当前仓库名是：

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 --global

link 完成后即可直接使用：

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-app

npm 发布流程

当前推荐使用 changesets + GitHub Actions 管理版本和发布，而不是长期依赖本地手工改版本。

发布前建议先确认：

已登录 npm：npm whoami
你的账号拥有该包名的发布权限
需要的话先把 package.json 里的 license 从 UNLICENSED 改成最终许可证
如果启用自动发布，需要在 GitHub 仓库中配置 NPM_TOKEN secret

推荐流程：

开发改动并提交
执行 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 模板示例

示例文件：

project.template.json

用法：

create-node-stack init --config ./examples/project.template.json

当前实现状态

当前已经完成并验证：

init
init --config
add app
add package
inquirer 交互式问答
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

注意事项

手动测试脚手架生成时，按仓库规则应先进入 examples 再创建测试项目
README 描述的是当前已经实现的行为；未来规划能力请看 docs