TanStack Config：JavaScript 包开发配置工具集

TanStack Config 是 TanStack 团队开源的一套配置工具集，旨在简化 JavaScript/TypeScript 包的开发、构建和发布流程。它提供了统一的 ESLint 配置、自动化的发布工具以及基于 Vite 的构建方案，让开发者能够以最小化的配置获得一致且高质量的开发体验。

核心特性

• 统一的 ESLint 配置：框架无关的共享配置，内置 TypeScript、导入检查和 Node.js 规则
• 自动化发布工具：支持 npm 和 GitHub 的自动化发布，内置 Trusted Publishing 支持
• Vite 构建配置：支持 ESM/CJS 双模式发布，兼容所有 TypeScript 模块解析选项
• 最小化配置：开箱即用，减少繁琐的配置工作

前置要求

使用 TanStack Config 需要以下环境：

• Node.js v20.17.0+
• Git CLI
• GitHub CLI（GitHub Actions 已预装）
• pnpm v10+（唯一支持的包管理器）

ESLint 配置

@tanstack/eslint-config 提供了 TanStack 项目间共享的 ESLint 配置，框架无关，不包含任何框架特定的插件。

安装

pnpm add -D @tanstack/eslint-config

配置

在 eslint.config.js 中导入并使用：

import { tanstackConfig } from '@tanstack/eslint-config'

export default [
  ...tanstackConfig,
  {
    // 自定义规则
  },
]

内置插件

• @eslint/js：核心 ESLint 规则
• typescript-eslint：TypeScript 支持
• eslint-plugin-import-x：导入/导出检查
• eslint-plugin-n：Node.js 实用规则

发布配置

@tanstack/publish-config 提供了自动化发布工具，简化 npm 和 GitHub 的发布流程。

安装

pnpm add -D @tanstack/publish-config

程序化使用

import { publish } from '@tanstack/publish-config'

publish({
  branchConfigs: configOpts.branchConfigs,
  packages: configOpts.packages,
  rootDir: configOpts.rootDir,
  branch: process.env.BRANCH,
  tag: process.env.TAG,
  ghToken: process.env.GH_TOKEN,
})
  .then(() => {
    console.log('Successfully published packages!')
  })
  .catch(console.error)

注意：程序化使用仅支持 ESM 包，需要在 package.json 中设置 "type": "module"。

Trusted Publishing

TanStack Config 支持 npm 的 Trusted Publishing 功能，允许通过 OIDC 认证发布包，无需手动管理 npm token。

配置步骤：

1. 对于未发布的包，先创建占位包
2. 使用工具批量配置多个包
3. 在 npm 包设置页面填写 GitHub 仓库信息

Vite 构建配置

@tanstack/vite-config 提供了支持 ESM/CJS 双模式发布的 Vite 构建配置。

安装

pnpm add -D @tanstack/vite-config

是否需要双模式发布？

ES Modules (ESM) 是 JavaScript 模块的标准格式。虽然历史上 CommonJS (CJS) 的兼容性问题较多，但现在 ESM 兼容性已大幅改善。建议优先考虑仅发布 ESM 版本。

各框架推荐方案

传统配置方式

如果你仍需要使用 @tanstack/vite-config，按以下步骤配置：

package.json

{
  "type": "module",
  "scripts": {
    "build": "vite build && publint --strict"
  },
  "exports": {
    ".": {
      "import": {
        "types": "./dist/esm/index.d.ts",
        "default": "./dist/esm/index.js"
      },
      "require": {
        "types": "./dist/cjs/index.d.cts",
        "default": "./dist/cjs/index.cjs"
      }
    },
    "./package.json": "./package.json"
  }
}

tsconfig.json

• 确保 include 字段包含 vite.config.ts
• 设置 moduleResolution 为 bundler

vite.config.ts

import { defineConfig, mergeConfig } from 'vite'
import { tanstackViteConfig } from '@tanstack/vite-config'

const config = defineConfig({
  // 框架插件、vitest 配置等
})

export default mergeConfig(
  config,
  tanstackViteConfig({
    entry: './src/index.ts',
    srcDir: './src',
  }),
)

项目链接

• GitHub 仓库：https://github.com/tanstack/config
• 官方文档：https://tanstack.com/config/latest
• npm 下载量：超过 200 万次