@talltydev/cli

v0.2.50

Published

7 months ago

Unified Tallty Kit CLI

0High
0Medium
0Low

Tallty Kit CLI

用于创建和管理 Next.js Web 应用 与 Taro 小程序 的统一命令行工具，集成 Tallty Kit 组件。采用现代化的叠加架构，专注于**"配置而非实现"*理念 —— UI/CRUD/S3 通过 @talltydev/ 包提供，认证部分直接下发可定制的 Better Auth 配置模板，Taro 模板则以轻量级 Handlebars 叠加保持与官方脚手架同步。

安装

通过 npm 全局安装：

npm install -g @talltydev/cli

Taro 模板概览

基于 Taro 4.1.7 + Webpack 5，保持与官方脚手架同步
自动叠加 5 个轻量级模板（fetch polyfill、Tailwind v4、PostCSS、package.json 补丁、weapp-tailwindcss 插件）
--monorepo 会将小程序移动至 apps/mini-app，并生成 packages/database/schema.zmodel
CLI 输出的下一步操作：
- 独立模式：pnpm install → pnpm dev:weapp
- Monorepo：pnpm install → pnpm db:generate → pnpm dev:weapp

⚠️ 排障提示：若出现 TARO_CLI_FAILED，通常是 npx @tarojs/cli init 网络调用失败。请检查网络后重新执行命令。

或使用 npx 直接运行：

npx @talltydev/cli create my-app --auth --ui

快速开始

创建一个带有认证和 UI 组件的新 Next.js 项目：

tallty-kit create my-awesome-app --auth --ui
cd my-awesome-app
npm install
npm run dev

创建一个独立的 Taro 小程序：

tallty-kit create my-mini-app --template taro
cd my-mini-app
pnpm install
pnpm dev:weapp

在现有 Monorepo 中新增一个应用（不指定时默认生成到 ./apps）：

cd /path/to/your-monorepo
tallty-kit add mobile-app --template taro --target apps/mobile

创建一个包含共享数据库的 Taro Monorepo：

tallty-kit create mini-super-app --template taro --monorepo
cd mini-super-app
pnpm install
pnpm db:generate
pnpm dev:weapp

命令详解

`create`

生成包含可选 Tallty Kit 组件的新项目。

tallty-kit create <项目名称> [选项]

参数：

<项目名称> - 要创建的项目名称（必需）

选项：

--auth - 包含 Better Auth 配置模板（服务端、客户端、中间件、Schema 示例）
--ui - 包含 shadcn/ui 组件库集成
--crud - 包含 CRUD 操作工具包
--s3 - 包含 AWS S3 上传工具包
--no-typescript - 使用 JavaScript 而非 TypeScript（默认：TypeScript）
--force - 如果目录存在则覆盖
--interactive - 启用交互式组件选择提示
--template <模板> - 使用的基础模板（nextjs-15、taro）
--target <目录> - 项目创建的目标目录
--verbose - 在生成过程中启用详细输出
--dry-run - 显示将要生成的内容但不创建文件
--db <数据库> - 数据库提供者（sqlite 或 postgresql，默认：sqlite）
--monorepo - Taro 模板下生成 apps/mini-app + packages/database

示例：

# 基础 Next.js 项目
tallty-kit create my-app

# 带认证的项目
tallty-kit create my-app --auth

# 包含所有组件的完整功能项目
tallty-kit create my-app --auth --ui --crud --s3

# JavaScript 项目（不使用 TypeScript）
tallty-kit create my-app --no-typescript

# 交互式组件选择
tallty-kit create my-app --interactive

# 自定义目标目录
tallty-kit create my-app --target ./projects/my-app

# 预览但不创建文件
tallty-kit create my-app --auth --ui --dry-run

# Taro 小程序（独立模式）
tallty-kit create my-mini-app --template taro

# Taro 小程序（Monorepo + 数据共享）
tallty-kit create analytics-mini --template taro --monorepo

`ui`

管理 shadcn/ui 风格的 UI 组件。此命令代理到 @talltydev/ui 包的 CLI 工具。

tallty-kit ui <子命令> [选项]

子命令：

`list`

列出所有可用的 UI 组件：

tallty-kit ui list

`add`

添加指定的 UI 组件到项目：

tallty-kit ui add <组件名...> [选项]

选项：

-p, --path <路径> - 目标目录（默认：'./components'）
--overwrite - 覆盖已存在的文件
-y, --yes - 跳过确认提示
--include-styles - 同时复制样式文件

示例：

# 添加按钮组件
tallty-kit ui add button

# 添加多个组件到指定目录
tallty-kit ui add button card dialog --path src/components

# 添加所有组件
tallty-kit ui add-all --include-styles

`layout`

管理布局组件。此命令代理到 @talltydev/layout 包的 CLI 工具。

tallty-kit layout <子命令> [选项]

子命令：

`list`

列出所有可用的布局组件：

tallty-kit layout list

`add`

添加指定的布局组件到项目：

tallty-kit layout add <组件名...> [选项]

选项：

-p, --path <路径> - 目标目录（默认：'./components'）
--overwrite - 覆盖已存在的文件
-y, --yes - 跳过确认提示
--include-styles - 同时复制样式文件

示例：

# 添加管理员布局
tallty-kit layout add admin-layout

# 添加多个布局组件
tallty-kit layout add admin-layout user-layout --path src/layouts

`crud`

生成 CRUD 操作界面。此命令代理到 @talltydev/crud-kit 包的 CLI 工具。

tallty-kit crud <子命令> [选项]

子命令：

`generate`

从 ZenStack 模型生成 CRUD 资源：

tallty-kit crud generate <模型名> [选项]

选项：

-p, --path <路径> - 输出目录路径（默认：'app'）
-n, --name <名称> - 资源名称（用于多变体资源）
-m, --mode <模式> - 生成模式（full, readonly, simple, minimal，默认：'full'）
--page-style <样式> - 页面模板样式（minimal, composition, custom，默认：'composition'）
--views <视图> - 要生成的视图（table,grid,list，默认：'table'）
--actions <操作> - 要包含的操作（create,edit,delete,view，默认：'create,edit,delete,view'）
--features <功能> - 要启用的功能（search,filters,bulk,export，默认：'search'）
--form-mode <模式> - 表单生成模式（auto,framework,custom，默认：'auto'）
--dry-run - 预览生成内容而不创建文件
--force - 覆盖已存在的文件
--interactive - 使用交互模式

`scan`

扫描并列出所有可用的模型：

tallty-kit crud scan [选项]

选项：

--schema <路径> - ZenStack 模式文件路径（默认：'schema.zmodel'）

示例：

# 为 User 模型生成完整的 CRUD
tallty-kit crud generate User

# 生成只读的用户列表
tallty-kit crud generate User --mode readonly --views table

# 交互式生成
tallty-kit crud generate --interactive

`auth`

认证系统脚手架工具。

tallty-kit auth <子命令> [选项]

`scaffold`

生成与 Better Auth 兼容的独立认证模型：

tallty-kit auth scaffold [选项]

选项：

-o, --output <文件> - 输出文件路径（默认：'schema.auth.zmodel'）
--force - 如果文件存在则覆盖
--dry-run - 打印生成的内容而不写入文件
--config <路径> - 包含额外字段/策略的 JSON 文件

示例：

# 生成基础认证模式
tallty-kit auth scaffold

# 生成到自定义文件
tallty-kit auth scaffold --output auth/models.zmodel

# 使用配置文件添加自定义字段
tallty-kit auth scaffold --config custom-fields.json

`list`

显示可用的模板和组件。

tallty-kit list [选项]

选项：

--json - 以 JSON 格式输出，用于编程使用

示例：

# 列出所有可用的模板和组件
tallty-kit list

# 获取 JSON 格式输出
tallty-kit list --json

架构概览

基于叠加的组件系统

Tallty Kit CLI 使用先进的叠加架构，消除代码重复并拥抱**"配置而非实现"**原则：

叠加式集成：UI/CRUD/S3 仍通过 @talltydev/* 包分发，Auth 叠加层提供可本地修改的 Better Auth 模板
叠加依赖：自动依赖解析（CRUD → UI, S3 → UI）
项目特定集成：生成的代码展示了正确的 NPM 包使用模式
灵活获取：可根据偏好选择 NPM 导入或 CLI 复制粘贴

组件获取策略

NPM 包方式（推荐）：

// 生成的项目使用 NPM 导入
import { Button } from '@talltydev/ui/button'
import { DataTable } from '@talltydev/crud-kit'
import { FileUpload } from '@talltydev/ui-upload'

CLI 复制粘贴替代方案：

# 可选择单独复制组件
tallty-kit ui add button
tallty-kit crud generate User
tallty-kit layout add admin-layout

生成的项目结构

使用 tallty-kit create 创建项目时，您将获得一个现代化的 Next.js 15 项目：

基础项目

Next.js 15 与 App Router
TypeScript（默认）或 JavaScript
Tailwind CSS 用于样式
ESLint 和 Prettier 已配置
Git 初始化与合理的 .gitignore

使用 `--auth` 标志

Better Auth 1.2+ 认证系统与 @daveyplate/better-auth-ui 集成
使用 Better Auth 组件预构建的登录/注册页面
Prisma 用户管理模式与 ZenStack 集成
环境配置模板和设置文档

使用 `--ui` 标志

@talltydev/ui NPM 包集成与项目特定的布局组件
为 shadcn/ui 兼容性预配置的 components.json
展示 NPM 包使用的头部和侧边栏集成示例
展示 @talltydev/ui 组件模式的仪表板页面
Radix UI 原语和 CVA（类变体权威）自动包含

使用 `--crud` 标志

@talltydev/crud-kit NPM 包集成与 TanStack Query 配置
ZenStack 数据层自动包含以增强 Prisma ORM
显示 DataTable 和表单集成模式的 CRUD 使用示例
@tanstack/react-query 的预配置查询客户端
展示 @talltydev/crud-kit 使用的管理面板示例

生成的设置文档

每个叠加都会生成全面的设置文档：

NPM 包集成指南

CRUD_SETUP.md：@talltydev/crud-kit 使用模式和 TanStack Query 集成
UPLOAD_SETUP.md：S3 文件上传的 @talltydev/ui-upload 配置
setup-ui.sh：@talltydev/ui 组件获取选项和工作区协议

组件获取选项

生成的项目提供以下指导：

NPM 导入：import { Button } from '@talltydev/ui/button'（推荐）
CLI 复制粘贴：tallty-kit ui add button（替代方法）
工作区协议：用于 monorepo 开发的 "@talltydev/ui": "workspace:*"

包依赖关系

@talltydev/cli (主CLI)
├── @talltydev/ui (UI组件)
├── @talltydev/layout (布局组件)
└── @talltydev/crud-kit (CRUD工具包)

认证配置：
- Better Auth 模板（服务端/客户端配置）
- 独立文件（无包依赖）

依赖链：
- CRUD → UI (CRUD 依赖 UI 组件)
- S3 → UI (文件上传依赖 UI 组件)
- Layout → UI (布局依赖基础 UI 组件)

项目要求

生成的项目需要：

Node.js 18+
npm、pnpm 或 yarn
支持 ES2022 的现代浏览器

所有生成的项目都可以立即运行：

cd your-project
npm install    # 安装依赖
npm run dev    # 启动开发服务器
npm run build  # 构建生产版本
npm test       # 运行测试

校验工具

修改 config/versions.json 或叠加模板时，建议运行版本校验脚本确保依赖矩阵保持一致：

pnpm --filter @talltydev/cli exec ./scripts/verify-versions.sh

该脚本通过 jq 检查外部依赖、Tallty workspace 协议以及各叠加清单的版本是否与 v4.0 规划一致。

组件集成

认证（Better Auth）

社交登录提供商（Google、GitHub 等）
邮箱/密码认证
会话管理
与 Prisma 的数据库集成

UI 组件（shadcn/ui）

基于 Radix UI 构建的可访问组件
使用 Tailwind CSS 完全可定制
TypeScript 支持
可树摇的导入

CRUD 操作

类型安全的数据操作
乐观更新
服务器状态管理
表单验证

模板系统

Tallty Kit CLI 使用基于文件的模板系统，提供灵活性和可维护性，同时确保生成项目的一致性。

模板架构

CLI 遵循叠加架构：

基础模板：最小的 Next.js 项目结构
组件叠加：特定功能的模块化添加
NPM 包依赖：核心功能的外部包

这种方法允许：

最小的基础项目（默认仅 Next.js + Tailwind）
通过叠加的可选高级功能
轻松维护和更新
一致的依赖管理

可用的基础模板

nextjs-15-tailwind-v4（默认）- 带 Tailwind CSS v4 的 Next.js 15

可用的叠加

| 叠加 | 描述 | 添加的 NPM 包 | |------|------|---------------| | auth | Better Auth 认证 | better-auth, @daveyplate/better-auth-ui | | ui | shadcn/ui 组件库 | @radix-ui/*, class-variance-authority | | crud | TanStack CRUD 操作 | @tanstack/react-query, zod | | zenstack | 全栈数据管理 | @zenstack/runtime, prisma | | s3 | 文件上传功能 | @aws-sdk/client-s3, @uppy/* |

模板变量

模板使用 Handlebars 进行变量替换：

| 变量 | 描述 | 示例 | |------|------|------| | projectName | 用户提供的项目名称 | my-awesome-app | | useTypeScript | 是否启用 TypeScript | true | | components | 选定组件的数组 | ['auth', 'ui'] | | targetDirectory | 目标目录路径 | /path/to/project | | template | 基础模板标识符 | nextjs-15-tailwind-v4 |

实际项目示例

电商项目示例

# 创建包含认证、UI和文件上传的电商项目
tallty-kit create ecommerce-store --auth --ui --crud
cd ecommerce-store

# 生成产品CRUD页面
tallty-kit crud generate Product --views "table,grid" --features "search,filters,export"

# 添加电商特定的布局
tallty-kit layout add shop-layout customer-layout

管理后台示例

# 创建完整的管理后台
tallty-kit create admin-dashboard --auth --ui --crud
cd admin-dashboard

# 生成用户管理
tallty-kit crud generate User --mode full --actions "create,edit,delete,view"

# 生成订单管理（只读）
tallty-kit crud generate Order --mode readonly --views table --features "search,filters,export"

# 添加管理布局
tallty-kit layout add admin-layout

SaaS 应用示例

# 创建SaaS应用基础
tallty-kit create saas-platform --auth --ui --crud
cd saas-platform

# 生成认证架构
tallty-kit auth scaffold --output prisma/auth.zmodel

# 生成用户和组织管理
tallty-kit crud generate User --features "search,bulk"
tallty-kit crud generate Organization --mode full

配置

CLI 使用合理的默认值，但可以自定义：

项目模板

nextjs-15-tailwind-v4（默认）- 带 Tailwind CSS v4 的 Next.js 15

组件兼容性

所有组件都设计为无缝协作：

Auth + UI：带 Better Auth 集成的样式化认证表单
UI + CRUD：带 shadcn/ui 的美观数据表格和表单
Auth + CRUD：带认证的受保护 CRUD 操作
ZenStack + CRUD：带类型安全的全栈数据管理
S3 + CRUD：CRUD 操作中的文件上传功能

开发工作流

生成项目

tallty-kit create my-project --auth --ui

开发
```
cd my-project
npm install
npm run dev
```

数据库设置（如果使用 --auth）

# 在 .env 中设置数据库 URL
echo "DATABASE_URL=your-database-url" > .env
npx prisma migrate dev

自定义
- 修改 src/components/ 中的组件
- 更新 src/lib/auth.ts 中的认证配置
- 自定义 tailwind.config.ts 中的 UI 主题

性能优化

项目生成通常需要：

基础项目：< 2 秒
带组件的项目：< 5 秒
完整项目（所有组件）：< 5 秒

生成的项目构建时间：

开发启动：< 10 秒
生产构建：< 30 秒

故障排除

常见问题

"找不到命令：tallty-kit"

确保 CLI 已全局安装：npm install -g @talltydev/cli
或使用 npx：npx @talltydev/cli create my-app

"目录已存在"

使用 --force 标志覆盖：tallty-kit create my-app --force
或选择不同的项目名称

"生成后的构建错误"

确保您已在项目目录中运行 npm install
检查您的 Node.js 版本是否为 18 或更高
尝试删除 node_modules 并重新运行 npm install

"认证不工作"

在 .env 中设置数据库 URL
运行 npx prisma migrate dev 设置数据库模式
在 src/lib/auth.ts 中配置认证提供商

"模板处理错误"

确保您有最新版本的 CLI：npm update -g @talltydev/cli
检查模板文件是否存在：tallty-kit list
验证项目名称仅包含有效字符（字母数字、连字符、下划线）
如果使用特殊字符，请尝试使用不同的项目名称

"包依赖冲突"

CLI 通过偏好更高版本自动解决版本冲突
如果遇到问题，请尝试清除 npm 缓存：npm cache clean --force
检查生成的 package.json 是否有明显的依赖问题

快速参考

最常用命令

# 创建项目
tallty-kit create <name> --auth --ui --crud

# 列出组件
tallty-kit ui list
tallty-kit layout list

# 添加组件
tallty-kit ui add button card
tallty-kit layout add admin-layout

# 生成CRUD
tallty-kit crud generate User

命令别名

# 这些命令是等价的：
tallty-kit ui add button
npx @talltydev/ui add button

tallty-kit crud generate User
npx @talltydev/crud-kit generate User

贡献

Tallty Kit CLI 是 Tallty Kit monorepo 的一部分。

开发设置

# 克隆仓库
git clone https://github.com/tallty/tallty-kit.git
cd tallty-kit

# 安装依赖
pnpm install

# 构建 CLI
pnpm --filter @talltydev/cli run build

# 本地测试
./packages/cli/dist/index.js create test-project

运行测试

# 运行所有 CLI 测试
pnpm test packages/cli

# 运行特定测试套件
pnpm test tests/contracts/cli-interface.test.ts
pnpm test tests/integration/
pnpm test tests/performance/

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Tallty Kit CLI

安装

Taro 模板概览

快速开始

命令详解

create

ui

list

add

layout

list

add

crud

generate

scan

auth

scaffold

list

架构概览

基于叠加的组件系统

组件获取策略

生成的项目结构

基础项目

使用 --auth 标志

使用 --ui 标志

使用 --crud 标志

生成的设置文档

NPM 包集成指南

组件获取选项

包依赖关系

项目要求

校验工具

组件集成

认证（Better Auth）

UI 组件（shadcn/ui）

CRUD 操作

模板系统

模板架构

可用的基础模板

可用的叠加

模板变量

实际项目示例

电商项目示例

管理后台示例

SaaS 应用示例

配置

项目模板

组件兼容性

开发工作流

性能优化

故障排除

常见问题

快速参考

最常用命令

命令别名

贡献

开发设置

运行测试

许可证

相关链接

`create`

`ui`

`list`

`add`

`layout`

`list`

`add`

`crud`

`generate`

`scan`

`auth`

`scaffold`

`list`

使用 `--auth` 标志

使用 `--ui` 标志

使用 `--crud` 标志