tanstack-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Overview

概述

TanStack CLI is an interactive scaffolding tool for creating TanStack Start applications. It provides guided project creation with 30+ pre-built integrations covering authentication, databases, deployment, and developer tools. It also includes an MCP (Model Context Protocol) server for AI agent assistance and supports custom templates for team-standardized setups.

Package:

@tanstack/cli

Status: Stable

TanStack CLI 是一款用于创建 TanStack Start 应用的交互式脚手架工具。它提供带引导的项目创建流程，涵盖身份验证、数据库、部署和开发者工具等领域的30+预构建集成。此外，它还包含用于AI Agent辅助的MCP（Model Context Protocol）服务器，并支持自定义模板以实现团队标准化项目配置。

包名：

@tanstack/cli

状态： 稳定版

Installation & Usage

安装与使用

bash

undefined

bash

undefined

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

undefined

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

undefined

Project Creation

项目创建

Interactive Mode

交互式模式

bash

npx @tanstack/cli create my-app

bash

npx @tanstack/cli create my-app

Prompts for:

会提示以下内容：

- Project name

- 项目名称

- Integration selection

- 集成选择

- Configuration options

- 配置选项

undefined

undefined

With Integrations Flag

使用集成参数

bash

undefined

bash

undefined

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

undefined

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

undefined

Available Integrations

可用集成

TanStack Libraries

TanStack 库

Integration	Description
`tanstack-query`	Async state management
`tanstack-form`	Type-safe form management
`tanstack-table`	Headless table/datagrid
`tanstack-store`	Reactive data store
`tanstack-virtual`	List virtualization
`tanstack-ai`	AI SDK integration
`tanstack-db`	Client-side database
`tanstack-pacer`	Debouncing/throttling utilities

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

Authentication

身份验证

Integration	Description
`clerk`	Clerk authentication
`better-auth`	Better Auth integration
`workos`	WorkOS identity management

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

Databases & ORMs

数据库与ORM

Integration	Description
`drizzle`	Drizzle ORM
`prisma`	Prisma ORM
`neon`	Neon serverless Postgres
`convex`	Convex backend platform

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

Deployment

部署

Integration	Description
`vercel`	Vercel deployment
`netlify`	Netlify deployment
`cloudflare`	Cloudflare Workers/Pages
`nitro`	Nitro server engine

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

Developer Tools

开发者工具

Integration	Description
`eslint`	ESLint configuration
`biome`	Biome linting/formatting
`shadcn-ui`	shadcn/ui component library
`storybook`	Storybook component development

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

API & Backend

API 与后端

Integration	Description
`trpc`	tRPC type-safe API
`orpc`	oRPC integration

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

Services

服务

Integration	Description
`sentry`	Error monitoring
`paraglide`	Internationalization (i18n)
`strapi`	Strapi CMS

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

Custom Templates

自定义模板

Creating a Template

创建模板

bash

undefined

bash

undefined

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

作为Git仓库或npm包分享

undefined

undefined

Using a Custom Template

使用自定义模板

bash

undefined

bash

undefined

From git repository

从Git仓库导入

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

undefined

npx @tanstack/cli create my-app --template ./templates/my-template

undefined

Template Structure

模板结构

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

my-template/
├── template.config.ts    # 模板配置文件
├── src/
│   ├── app/
│   │   ├── routes/
│   │   └── components/
│   └── lib/
├── package.json
├── tsconfig.json
├── app.config.ts
└── vite.config.ts

MCP Server

MCP 服务器

The TanStack CLI includes an MCP (Model Context Protocol) server for AI agent integration.

TanStack CLI 包含用于AI Agent集成的MCP（Model Context Protocol）服务器。

Capabilities

功能

Documentation Search - AI agents can query TanStack documentation
Project Scaffolding - Guided project creation through AI assistants
Integration Discovery - Search and recommend integrations
Deployment Guidance - Platform-specific deployment help

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

Usage with Claude

与 Claude 配合使用

The MCP server enables Claude and other AI assistants to:

Search TanStack docs for accurate, up-to-date information
Help scaffold new projects with appropriate integrations
Provide context-aware recommendations
Assist with configuration and deployment

MCP 服务器支持 Claude 及其他AI助手：

搜索 TanStack 文档以获取准确、实时的信息
协助搭建包含合适集成的新项目
提供上下文感知的推荐建议
协助完成配置与部署工作

Configuration

配置

json

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

json

// .claude/mcp.json 或等效文件
{
  "mcpServers": {
    "tanstack": {
      "command": "npx",
      "args": ["@tanstack/cli", "mcp"]
    }
  }
}

Generated Project Structure

生成的项目结构

A typical generated project looks like:

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

典型的生成项目结构如下：

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

Web Builder Interface

Web 构建器界面

TanStack CLI also provides an interactive web-based builder:

Visual technology stack selection
Preview generated files before exporting
Integration compatibility checking
One-click project generation

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

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

CLI Commands Reference

CLI 命令参考

Command	Description
`create <name>`	Create a new project
`create <name> --integrations <list>`	Create with specific integrations
`create <name> --template <path>`	Create from template
`mcp`	Start the MCP server

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

Best Practices

最佳实践

Start with minimal integrations - add more as needed rather than including everything upfront
Use the
--integrations
flag for reproducible project creation in CI/docs
Create team templates for consistent project structure across your organization
Use the MCP server with AI assistants for guided setup
Check
.env.example
after generation for required environment variables
Review generated code before adding business logic - understand the scaffold
Use deployment integrations to pre-configure hosting platform settings
Combine auth + db integrations for full-stack auth scaffolding (e.g.,
```
clerk,drizzle,neon
```
)

从最少集成开始 - 按需添加集成，而非一开始就包含所有内容
使用
--integrations
参数 - 在CI/文档中实现可复现的项目创建
创建团队模板 - 确保组织内项目结构的一致性
搭配MCP服务器与AI助手 - 获得引导式的项目设置体验
生成后查看
.env.example
- 了解所需的环境变量
添加业务逻辑前审阅生成的代码 - 理解脚手架的结构
使用部署集成 - 预配置托管平台的设置
组合身份验证+数据库集成 - 搭建全栈身份验证脚手架（例如
```
clerk,drizzle,neon
```
）

Common Pitfalls

常见陷阱

Not setting up environment variables after project creation (check
```
.env.example
```
)
Selecting incompatible integration combinations
Not running
```
npm install
```
/
```
pnpm install
```
after generation
Forgetting to initialize the database when using Drizzle/Prisma integrations
Not configuring the deployment platform's environment variables
Using outdated CLI version (always use
```
npx @tanstack/cli
```
for latest)

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