Back to Details

tanstack-cli

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

TanStack Config

TanStack Config

Overview

概述

TanStack Config provides opinionated tooling to build, version, and publish JavaScript/TypeScript packages with minimal configuration and consistent results. It uses Vite for library builds with automatic dual ESM/CJS output and type generation, plus automated publishing with conventional-commit-based versioning.
When to use: Building TanStack libraries or packages that follow TanStack conventions, contributing to TanStack open-source projects, setting up dual ESM/CJS library builds with Vite, automating package publishing with conventional commits.
When NOT to use: Application builds (use framework-specific tooling), non-library projects, projects not using pnpm, projects that need non-Vite build pipelines.
TanStack Config 提供约定式工具，可通过最少配置实现JavaScript/TypeScript包的构建、版本化与发布，并保证结果一致性。它采用Vite进行库构建，自动生成ESM/CJS双格式输出及类型定义，同时支持基于约定式提交的自动化版本管理与发布。
适用场景：构建遵循TanStack惯例的TanStack库或包，为TanStack开源项目做贡献，使用Vite搭建ESM/CJS双输出的库构建流程，通过约定式提交实现包发布自动化。
不适用场景：应用构建（请使用框架专属工具），非库类项目，不使用pnpm的项目，需要非Vite构建流水线的项目。

Quick Reference

快速参考

PatternAPI / PackageKey Points
Vite build config
tanstackViteConfig()
from 
@tanstack/vite-config
Merge with 
defineConfig
via 
mergeConfig
Entry point
entry: './src/index.ts'
Single file or array of entry files
Source directory
srcDir: './src'
Used for declaration file generation
CJS output
cjs: true
(default)		Generates 
.cjs
and 
.d.cts
alongside ESM
External deps
externalDeps: [/^@internal\//]
Auto-detected from 
package.json
, extend with patterns
Bundled deps
bundledDeps: ['tiny-invariant']
Bundle instead of externalize
Exclude from types
exclude: ['./src/**/*.test.ts']
Patterns to skip during type generation
Custom tsconfig
tsconfigPath: './tsconfig.build.json'
Override default tsconfig for builds
Declaration hook
beforeWriteDeclarationFile(path, content)
Transform 
.d.ts
content before write
Publish automation
publish()
from 
@tanstack/publish-config
Conventional commits drive versioning
Branch configs
branchConfigs: { main, beta, alpha }
Control prerelease and stable channels
Package list
packages: [{ name, packageDir }]
Monorepo package definitions
Build script
vite build && publint --strict
Standard build with strict linting
模式API / 包关键点
Vite构建配置
@tanstack/vite-config
中的 
tanstackViteConfig()
通过
mergeConfig
与
defineConfig
合并使用
入口文件
entry: './src/index.ts'
单个文件或多个文件组成的数组
源码目录
srcDir: './src'
用于生成声明文件
CJS输出
cjs: true
（默认值）		在ESM输出之外同时生成
.cjs
和
.d.cts
文件
外部依赖
externalDeps: [/^@internal\//]
从
package.json
自动检测，可通过模式扩展
打包依赖
bundledDeps: ['tiny-invariant']
打包进库而非标记为外部依赖
类型排除文件
exclude: ['./src/**/*.test.ts']
类型生成过程中需要跳过的文件模式
自定义tsconfig
tsconfigPath: './tsconfig.build.json'
覆盖构建使用的默认tsconfig
声明文件钩子
beforeWriteDeclarationFile(path, content)
在写入
.d.ts
文件前转换内容
发布自动化
@tanstack/publish-config
中的 
publish()
基于约定式提交驱动版本管理
分支配置
branchConfigs: { main, beta, alpha }
控制预发布和稳定版本渠道
包列表
packages: [{ name, packageDir }]
单仓库多包（Monorepo）的包定义
构建脚本
vite build && publint --strict
带严格检查的标准构建流程

Common Mistakes

常见错误

MistakeCorrect Pattern
Missing 
"type": "module"
in 
package.json
Set 
"type": "module"
for ESM-first builds
Using 
defineConfig
alone without 
mergeConfig
Use 
mergeConfig(defineConfig({...}), tanstackViteConfig({...}))
Forgetting 
entry
or 
srcDir
options		Both are required for 
tanstackViteConfig
to work
Missing 
exports
field in 
package.json
Define 
import
and 
require
conditions with types
Not awaiting 
publish()
promise		Handle with 
.then()
and 
.catch()
for error reporting
Using npm or yarn instead of pnpmpnpm is the only supported package manager
Omitting 
publint --strict
from build script		Add 
publint --strict
after 
vite build
to catch packaging issues
Setting 
tag
without 
v
prefix		Manual version tags must start with 
v
(e.g., 
v1.0.0
)
Wrong commit type for release level
fix
/
refactor
/
perf
= patch, 
feat
= minor, 
BREAKING CHANGE
= major
错误做法正确方式
package.json
中缺少
"type": "module"
字段		对于ESM优先的构建，设置
"type": "module"
单独使用
defineConfig
而不搭配
mergeConfig
使用
mergeConfig(defineConfig({...}), tanstackViteConfig({...}))
遗漏
entry
或
srcDir
配置项		这两个配置项是
tanstackViteConfig
正常工作的必填项
package.json
中缺少
exports
字段		定义包含类型的
import
和
require
条件
未等待
publish()
的Promise结果		使用
.then()
和
.catch()
处理以捕获错误并报告
使用npm或yarn而非pnpmpnpm是唯一支持的包管理器
构建脚本中省略
publint --strict
在
vite build
之后添加
publint --strict
以捕获打包问题
设置
tag
时没有
v
前缀		手动版本标签必须以
v
开头（例如：
v1.0.0
）
提交类型与发布版本级别不匹配
fix
/
refactor
/
perf
对应补丁版本，
feat
对应小版本，
BREAKING CHANGE
对应大版本

Requirements

依赖要求

  • Node.js v18.17+
  • pnpm v8+
  • Git CLI
  • GitHub CLI (pre-installed on GitHub Actions)
  • Vite (peer dependency for build config)
  • publint (recommended for build validation)
  • Node.js v18.17+
  • pnpm v8+
  • Git CLI
  • GitHub CLI（GitHub Actions中已预装）
  • Vite（构建配置的对等依赖）
  • publint（推荐用于构建验证）

Delegation

任务委托

  • Build configuration review: Use 
    Task
    agent to verify Vite config and 
    package.json
    exports
  • Publishing workflow setup: Use 
    Explore
    agent to check CI/CD integration patterns
  • Package validation: Run 
    publint --strict
    after builds to catch packaging issues
  • 构建配置审核：使用
    Task
    代理验证Vite配置和
    package.json
    的exports字段
  • 发布工作流设置：使用
    Explore
    代理检查CI/CD集成模式
  • 包验证：构建后运行
    publint --strict
    以捕获打包问题

References

参考资料

  • Configuration and Vite plugin setup
  • Publishing and version management
  • 配置与Vite插件设置
  • 发布与版本管理