tanstack-config

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Overview

概述

TanStack Config provides an opinionated, minimal-configuration toolkit for JavaScript/TypeScript package development. It includes Vite-powered build configuration, ESLint presets, publish automation with semantic versioning, and integrations with TypeScript, Prettier, Changesets, and GitHub Actions. Designed for monorepo workflows with pnpm and Nx.

Package:

@tanstack/config

Status: Stable

TanStack Config 是一款面向JavaScript/TypeScript包开发的约定式、极简配置工具集。它包含基于Vite的构建配置、ESLint预设、带语义化版本控制的发布自动化功能，并与TypeScript、Prettier、Changesets和GitHub Actions集成。专为pnpm和Nx的单仓库（monorepo）工作流设计。

包名：

@tanstack/config

状态： 稳定版

Installation

安装

bash

npm install @tanstack/config --save-dev

bash

npm install @tanstack/config --save-dev

or

pnpm add @tanstack/config -D

undefined

pnpm add @tanstack/config -D

undefined

Vite Build Configuration

Vite构建配置

Basic Setup

基础设置

typescript

// vite.config.ts
import { defineConfig, mergeConfig } from 'vitest/config'
import { tanstackViteConfig } from '@tanstack/config/vite'

const config = defineConfig({
  // Your custom Vite config
})

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

typescript

// vite.config.ts
import { defineConfig, mergeConfig } from 'vitest/config'
import { tanstackViteConfig } from '@tanstack/config/vite'

const config = defineConfig({
  // 你的自定义Vite配置
})

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

Multiple Entry Points

多入口配置

typescript

import { tanstackViteConfig } from '@tanstack/config/vite'

export default tanstackViteConfig({
  entry: [
    './src/index.ts',
    './src/adapters.ts',
    './src/utils.ts',
  ],
  srcDir: './src',
})

typescript

import { tanstackViteConfig } from '@tanstack/config/vite'

export default tanstackViteConfig({
  entry: [
    './src/index.ts',
    './src/adapters.ts',
    './src/utils.ts',
  ],
  srcDir: './src',
})

Build Options

构建选项

typescript

tanstackViteConfig({
  entry: './src/index.ts',
  srcDir: './src',
  exclude: ['./src/__tests__', './src/**/*.test.ts'],
  // Generates ESM and CJS outputs
  // Generates .d.ts declaration files
  // Handles tree-shaking configuration
})

typescript

tanstackViteConfig({
  entry: './src/index.ts',
  srcDir: './src',
  exclude: ['./src/__tests__', './src/**/*.test.ts'],
  // 生成ESM和CJS输出
  // 生成.d.ts声明文件
  // 处理摇树优化配置
})

ESLint Configuration

ESLint配置

Basic Setup

基础设置

javascript

// eslint.config.js
import { tanstackEslintConfig } from '@tanstack/config/eslint'

export default tanstackEslintConfig

javascript

// eslint.config.js
import { tanstackEslintConfig } from '@tanstack/config/eslint'

export default tanstackEslintConfig

Extending the Config

扩展配置

javascript

// eslint.config.js
import { tanstackEslintConfig } from '@tanstack/config/eslint'

export default [
  ...tanstackEslintConfig,
  {
    rules: {
      // Custom overrides
      '@typescript-eslint/no-explicit-any': 'warn',
    },
  },
]

javascript

// eslint.config.js
import { tanstackEslintConfig } from '@tanstack/config/eslint'

export default [
  ...tanstackEslintConfig,
  {
    rules: {
      // 自定义规则覆盖
      '@typescript-eslint/no-explicit-any': 'warn',
    },
  },
]

Publishing

发布配置

Publish Configuration

发布配置文件

typescript

// publish.config.ts or used via CLI
import { tanstackPublishConfig } from '@tanstack/config/publish'

export default tanstackPublishConfig({
  // Publint-compliant defaults
  // Semantic versioning automation
  // Changelog generation
})

typescript

// publish.config.ts 或通过CLI使用
import { tanstackPublishConfig } from '@tanstack/config/publish'

export default tanstackPublishConfig({
  // 符合publint规范的默认配置
  // 语义化版本自动化
  // 变更日志生成
})

Package.json Setup

Package.json设置

json

{
  "name": "@myorg/my-package",
  "version": "0.0.0",
  "type": "module",
  "main": "dist/cjs/index.cjs",
  "module": "dist/esm/index.js",
  "types": "dist/esm/index.d.ts",
  "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"
      }
    }
  },
  "files": ["dist", "src"],
  "scripts": {
    "build": "vite build",
    "lint": "eslint .",
    "test": "vitest"
  }
}

json

{
  "name": "@myorg/my-package",
  "version": "0.0.0",
  "type": "module",
  "main": "dist/cjs/index.cjs",
  "module": "dist/esm/index.js",
  "types": "dist/esm/index.d.ts",
  "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"
      }
    }
  },
  "files": ["dist", "src"],
  "scripts": {
    "build": "vite build",
    "lint": "eslint .",
    "test": "vitest"
  }
}

TypeScript Configuration

TypeScript配置

tsconfig.json

json

{
  "compilerOptions": {
    "strict": true,
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

json

{
  "compilerOptions": {
    "strict": true,
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

Changesets Integration

Changesets集成

Setup

初始化

bash

npx changeset init

bash

npx changeset init

Creating a Changeset

创建变更集

bash

npx changeset

bash

npx changeset

Interactive prompt: select packages, bump type, summary

交互式提示：选择包、版本变更类型、变更摘要

undefined

undefined

Changeset Config

Changeset配置

json

// .changeset/config.json
{
  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
  "changelog": "@changesets/cli/changelog",
  "commit": false,
  "fixed": [],
  "linked": [],
  "access": "public",
  "baseBranch": "main",
  "updateInternalDependencies": "patch"
}

json

// .changeset/config.json
{
  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
  "changelog": "@changesets/cli/changelog",
  "commit": false,
  "fixed": [],
  "linked": [],
  "access": "public",
  "baseBranch": "main",
  "updateInternalDependencies": "patch"
}

GitHub Actions Workflow

GitHub Actions工作流

CI/CD Pipeline

CI/CD流水线

yaml

undefined

yaml

undefined

.github/workflows/ci.yml

on: push: branches: [main] pull_request: branches: [main]

jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: pnpm/action-setup@v2 - uses: actions/setup-node@v4 with: node-version: 20 cache: 'pnpm' - run: pnpm install - run: pnpm build - run: pnpm lint - run: pnpm test

undefined

on: push: branches: [main] pull_request: branches: [main]

undefined

Publish Workflow

发布工作流

yaml

undefined

yaml

undefined

.github/workflows/publish.yml

on: push: branches: [main]

jobs: publish: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: pnpm/action-setup@v2 - uses: actions/setup-node@v4 with: node-version: 20 registry-url: 'https://registry.npmjs.org' - run: pnpm install - run: pnpm build - name: Create Release Pull Request or Publish uses: changesets/action@v1 with: publish: pnpm publish -r env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

undefined

on: push: branches: [main]

undefined

Monorepo Setup (pnpm + Nx)

单仓库（Monorepo）设置（pnpm + Nx）

Workspace Configuration

工作区配置

yaml

undefined

yaml

undefined

pnpm-workspace.yaml

packages:

'packages/*'
'examples/*'

undefined

packages:

'packages/*'
'examples/*'

undefined

Nx Configuration

Nx配置

json

// nx.json
{
  "tasksRunnerOptions": {
    "default": {
      "runner": "nx/tasks-runners/default",
      "options": {
        "cacheableOperations": ["build", "lint", "test"]
      }
    }
  },
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"]
    }
  }
}

json

// nx.json
{
  "tasksRunnerOptions": {
    "default": {
      "runner": "nx/tasks-runners/default",
      "options": {
        "cacheableOperations": ["build", "lint", "test"]
      }
    }
  },
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"]
    }
  }
}

Prettier Configuration

Prettier配置

json

// .prettierrc
{
  "semi": false,
  "singleQuote": true,
  "trailingComma": "all",
  "printWidth": 80
}

json

// .prettierrc
{
  "semi": false,
  "singleQuote": true,
  "trailingComma": "all",
  "printWidth": 80
}

EditorConfig

ini

undefined

ini

undefined

.editorconfig

root = true

[*] indent_style = space indent_size = 2 end_of_line = lf charset = utf-8 trim_trailing_whitespace = true insert_final_newline = true

undefined

root = true

[*] indent_style = space indent_size = 2 end_of_line = lf charset = utf-8 trim_trailing_whitespace = true insert_final_newline = true

undefined

Best Practices

最佳实践

Use the Vite config for builds - handles ESM/CJS dual output and declarations
Use publint-compliant exports in package.json for compatibility
Use Changesets for version management in monorepos
Set
"type": "module"
in package.json for ESM-first packages
Include both
src
and
dist
in
```
files
```
for source map debugging
Use Nx caching for faster builds in monorepos
Always generate declaration files (
```
.d.ts
```
) for TypeScript consumers
Use the ESLint config as a consistent baseline across packages
Automate publishing with GitHub Actions and Changesets

使用Vite配置进行构建 - 处理ESM/CJS双输出和声明文件
在package.json中使用符合publint规范的exports字段以确保兼容性
使用Changesets进行单仓库的版本管理
**在package.json中设置
```
"type": "module"
```
**以实现ESM优先的包
**在
```
files
```
字段中同时包含
```
src
```
和
```
dist
```
**以支持源码映射调试
使用Nx缓存以加速单仓库的构建
**始终生成声明文件（
```
.d.ts
```
）**以方便TypeScript用户
使用ESLint配置作为跨包的一致性基准
通过GitHub Actions和Changesets自动化发布流程

Common Pitfalls

常见陷阱

Missing
```
exports
```
field in package.json (breaks modern bundlers)
Not setting
```
"type": "module"
```
(causes ESM import issues)
Forgetting declaration files in build output
Not excluding test files from the build
Publishing without running publint validation first
Not configuring
```
moduleResolution: "bundler"
```
in tsconfig
Inconsistent versioning across monorepo packages (use Changesets
```
linked
```
)

package.json中缺少
```
exports
```
字段（会导致现代打包工具出错）
未设置
```
"type": "module"
```
（会引发ESM导入问题）
构建输出中遗漏声明文件
未从构建中排除测试文件
未先运行publint验证就发布
未在tsconfig中配置
```
moduleResolution: "bundler"
```
单仓库中包的版本不一致（使用Changesets的
```
linked
```
配置）