tanstack-cli

概述

TanStack CLI 是一款交互式脚手架工具，用于创建 TanStack Start 应用。它提供引导式项目创建流程，涵盖 30 多种预构建集成，包括身份验证、数据库、部署和开发者工具。它还包含一个 MCP（Model Context Protocol）服务，用于 AI Agent 助手，并支持自定义模板，以便团队采用统一的配置。

软件包： @tanstack/cli 状态： 稳定

安装与使用

# Create a new project (interactive)
npx @tanstack/cli create my-app

# Create with specific integrations
npx @tanstack/cli create my-app --integrations tanstack-query,clerk,drizzle

# Global install
npm install -g @tanstack/cli
tanstack create my-app

创建项目

交互模式

npx @tanstack/cli create my-app
# Prompts for:
# - Project name
# - Integration selection
# - Configuration options

使用集成标志

# Multiple integrations
npx @tanstack/cli create my-app --integrations tanstack-query,tanstack-form,drizzle,neon,clerk

# Deployment target
npx @tanstack/cli create my-app --integrations vercel

# Full stack setup
npx @tanstack/cli create my-app --integrations tanstack-query,tanstack-form,tanstack-table,clerk,drizzle,neon,vercel,sentry

可用集成

TanStack 库

集成	描述
tanstack-query	异步状态管理
tanstack-form	类型安全的表单管理
tanstack-table	无头表格/数据网格
tanstack-store	响应式数据存储
tanstack-virtual	列表虚拟化
tanstack-ai	AI SDK 集成
tanstack-db	客户端数据库
tanstack-pacer	防抖/节流工具

身份验证

集成	描述
clerk	Clerk 身份验证
better-auth	Better Auth 集成
workos	WorkOS 身份管理

数据库与 ORM

集成	描述
drizzle	Drizzle ORM
prisma	Prisma ORM
neon	Neon 无服务器 Postgres
convex	Convex 后端平台

部署

集成	描述
vercel	Vercel 部署
netlify	Netlify 部署
cloudflare	Cloudflare Workers/Pages
nitro	Nitro 服务引擎

开发者工具

集成	描述
eslint	ESLint 配置
biome	Biome 代码检查/格式化
shadcn-ui	shadcn/ui 组件库
storybook	Storybook 组件开发

API 与后端

集成	描述
trpc	tRPC 类型安全 API
orpc	oRPC 集成

服务

集成	描述
sentry	错误监控
paraglide	国际化（i18n）
strapi	Strapi CMS

自定义模板

创建模板

# Create a project as a template base
npx @tanstack/cli create my-template --integrations tanstack-query,drizzle,clerk

# Share as a git repository or npm package

使用自定义模板

# From git repository
npx @tanstack/cli create my-app --template https://github.com/myorg/my-template

# From local path
npx @tanstack/cli create my-app --template ./templates/my-template

模板结构

my-template/
├── template.config.ts    # Template configuration
├── src/
│   ├── app/
│   │   ├── routes/
│   │   └── components/
│   └── lib/
├── package.json
├── tsconfig.json
├── app.config.ts
└── vite.config.ts

MCP 服务

TanStack CLI 包含一个 MCP（Model Context Protocol）服务，用于集成 AI Agent。

功能

• 文档搜索 - AI Agent 可以查询 TanStack 文档
• 项目脚手架 - 通过 AI 助手引导创建项目
• 集成发现 - 搜索并推荐集成
• 部署指导 - 提供针对特定平台的部署帮助

与 Claude 搭配使用

MCP 服务让 Claude 和其他 AI 助手能够：

• 搜索 TanStack 文档，获取准确且最新的信息
• 帮助使用适当的集成搭建新项目
• 提供上下文感知的建议
• 协助配置和部署

配置

// .claude/mcp.json or equivalent
{
  "mcpServers": {
    "tanstack": {
      "command": "npx",
      "args": ["@tanstack/cli", "mcp"]
    }
  }
}

生成的项目结构

典型的生成项目如下：

my-app/
├── src/
│   ├── app/
│   │   ├── routes/
│   │   │   ├── __root.tsx
│   │   │   └── index.tsx
│   │   ├── router.tsx
│   │   ├── routeTree.gen.ts
│   │   └── client.tsx
│   ├── lib/
│   │   ├── db.ts          # (if drizzle/prisma)
│   │   ├── auth.ts        # (if clerk/better-auth)
│   │   └── query.ts       # (if tanstack-query)
│   └── components/
├── app.config.ts
├── vite.config.ts
├── package.json
├── tsconfig.json
└── .env.example

Web 构建器界面

TanStack CLI 还提供交互式 Web 构建器：

• 可视化选择技术栈
• 导出前预览生成的文件
• 检查集成兼容性
• 一键生成项目

CLI 命令参考

命令	描述
create <name>	创建新项目
create <name> --integrations <list>	使用指定集成创建项目
create <name> --template <path>	使用模板创建项目
mcp	启动 MCP 服务

最佳实践

1. 从最精简的集成开始——按需添加，而不是一开始就全部引入
2. 使用 --integrations 标志，以便在 CI/文档中可复现地创建项目
3. 创建团队模板，确保组织内的项目结构一致
4. 将 MCP 服务与 AI 助手搭配使用，以获得引导式设置
5. 生成后检查 .env.example，了解所需的环境变量
6. 添加业务逻辑前先检查生成的代码——了解脚手架的内容
7. 使用部署集成，预先配置托管平台设置
8. 组合使用身份验证和数据库集成，生成完整的全栈身份验证脚手架（例如，clerk,drizzle,neon）

常见问题

• 创建项目后未设置环境变量（检查 .env.example）
• 选择了不兼容的集成组合
• 生成后未运行 npm install / pnpm install
• 使用 Drizzle/Prisma 集成时忘记初始化数据库
• 未配置部署平台的环境变量
• 使用了过时的 CLI 版本（始终使用最新版本的 npx @tanstack/cli）