tanstack-config

概述

TanStack Config 为 JavaScript/TypeScript 包开发提供了一套主张明确、配置精简的工具包。它包含由 Vite 驱动的构建配置、ESLint 预设、采用语义化版本控制的发布自动化，以及与 TypeScript、Prettier、Changesets 和 GitHub Actions 的集成。专为使用 pnpm 和 Nx 的单体仓库工作流而设计。

包： @tanstack/config 状态： 稳定

安装

npm install @tanstack/config --save-dev
# or
pnpm add @tanstack/config -D

Vite 构建配置

基本设置

// 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__'],
  })
)

多个入口点

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

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

构建选项

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
})

ESLint 配置

基本设置

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

export default tanstackEslintConfig

扩展配置

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

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

发布

发布配置

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

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

Package.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 配置

tsconfig.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 集成

设置

npx changeset init

创建 Changeset

npx changeset
# Interactive prompt: select packages, bump type, summary

Changeset 配置

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

GitHub Actions 工作流

CI/CD 流水线

# .github/workflows/ci.yml
name: CI

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

发布工作流

# .github/workflows/publish.yml
name: Publish

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 }}

单体仓库设置（pnpm + Nx）

工作区配置

# pnpm-workspace.yaml
packages:
  - 'packages/*'
  - 'examples/*'

Nx 配置

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

Prettier 配置

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

EditorConfig

# .editorconfig
root = true

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

最佳实践

1. 使用 Vite 配置进行构建 - 处理 ESM/CJS 双格式输出和声明文件
2. 在 package.json 中使用符合 publint 规范的 exports，确保兼容性
3. 使用 Changesets 管理单体仓库中的版本
4. 在 package.json 中设置 "type": "module"，用于 ESM 优先的包
5. 在 files 中同时包含 src 和 dist，以便调试源映射
6. 使用 Nx 缓存，加快单体仓库中的构建速度
7. 始终生成声明文件（.d.ts），供 TypeScript 使用者使用
8. 使用 ESLint 配置，作为各个包的一致基准
9. 使用 GitHub Actions 和 Changesets 自动化发布

常见问题

• package.json 中缺少 exports 字段（会导致现代打包工具无法正常工作）
• 未设置 "type": "module"（会导致 ESM 导入问题）
• 忘记在构建输出中包含声明文件
• 未将测试文件排除在构建之外
• 发布前未运行 publint 验证
• 未在 tsconfig 中配置 moduleResolution: "bundler"
• 单体仓库各个包的版本不一致（使用 Changesets 的 linked）