mcpField
T
tanstack-cli

tanstack-cli

github.com/oakoss开发21109 次安装12 周前更新
代码仓库

关于 tanstack-cli

tanstack-cli 提供 TanStack 风格 JavaScript/TypeScript 包的构建、版本管理与发布工具，面向库和包开发者。它基于 Vite 生成 ESM/CJS 输出和类型声明，并可按 Conventional Commits 自动确定发布版本。

主要功能

  1. 01Vite 库构建配置
  2. 02生成 ESM/CJS 与类型声明
  3. 03自动识别外部依赖
  4. 04按 Conventional Commits 管理版本
  5. 05配置稳定版与预发布分支

适用场景

  1. 01构建 TanStack 风格的 JavaScript/TypeScript 库
  2. 02为库生成双模块格式和类型声明
  3. 03通过提交记录自动化包发布

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/oakoss/agent-skills --skill tanstack-cli

安装后在 Claude Code 中输入/tanstack-cli确认已加载。

附带文件references/configuration.mdreferences/publishing.md

详细介绍

TanStack Config

概述

TanStack Config 提供开箱即用的工具，用于构建、管理版本并发布 JavaScript/TypeScript 包，只需极少配置即可获得一致的结果。它使用 Vite 构建库，自动生成 ESM/CJS 双格式输出和类型文件，并支持基于约定式提交自动发布和管理版本。

适用场景： 构建遵循 TanStack 约定的 TanStack 库或包，为 TanStack 开源项目做贡献，使用 Vite 设置 ESM/CJS 双格式库构建，以及通过约定式提交自动发布包。

不适用场景： 应用构建（请使用框架专用工具）、非库项目、不使用 pnpm 的项目，以及需要使用非 Vite 构建流程的项目。

快速参考

模式API / 包要点
Vite 构建配置tanstackViteConfig() from @tanstack/vite-config通过 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']类型生成时跳过的模式
自定义 tsconfigtsconfigPath: './tsconfig.build.json'为构建指定非默认的 tsconfig
声明文件钩子beforeWriteDeclarationFile(path, content)写入前转换 .d.ts 内容
发布自动化publish() from @tanstack/publish-config通过约定式提交管理版本
分支配置branchConfigs: { main, beta, alpha }控制预发布和稳定版渠道
包列表packages: [{ name, packageDir }]Monorepo 包定义
构建脚本vite build && publint --strict使用严格检查的标准构建

常见错误

错误正确做法
在 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 = 主要版本

要求

  • Node.js v18.17+
  • pnpm v8+
  • Git CLI
  • GitHub CLI（已预装在 GitHub Actions 中）
  • Vite（构建配置的对等依赖）
  • publint（推荐用于构建验证）

委派

  • 构建配置审查：使用 Task agent 验证 Vite 配置和 package.json 导出
  • 发布工作流设置：使用 Explore agent 检查 CI/CD 集成模式
  • 包验证：构建后运行 publint --strict，以发现打包问题

参考资料

评论

支持 Markdown