在开发/发布 JavaScript/TypeScript…

为 JavaScript/TypeScript 包（尤其是 monorepo）快速搭建构建、lint、版本管理与自动化发布流程。

适用场景

解决思路

1. 安装 @tanstack/config 作为开发依赖：运行 `npm install @tanstack/config --save-dev`，或运行 `pnpm add @tanstack/config -D`。
2. 在 vite.config.ts 中导入 `defineConfig`、`mergeConfig` 和 `tanstackViteConfig`，先用 `defineConfig` 定义自定义 Vite 配置，再用 `mergeConfig` 合并 `tanstackViteConfig({ entry: './src/index.ts', srcDir: './src', exclude: ['./src/__tests__'] })`。
3. 多入口构建时，将 `entry` 传入数组，例如 `['./src/index.ts', './src/adapters.ts', './src/utils.ts']`，并设置 `srcDir: './src'`。
4. 在 `tanstackViteConfig` 的构建选项中设置 `exclude: ['./src/__tests__', './src/**/*.test.ts']`；该配置会生成 ESM 和 CJS 输出、生成 `.d.ts` 声明文件并处理 tree-shaking。
5. 在 eslint.config.js 中导入 `tanstackEslintConfig` 并默认导出它，作为基础 ESLint 配置。
6. 扩展 ESLint 配置时，在数组中展开 `...tanstackEslintConfig`，再追加自定义规则对象，例如设置 `'@typescript-eslint/no-explicit-any': 'warn'`。
7. 通过 `publish.config.ts` 或 CLI 使用 `tanstackPublishConfig({})`，以获得 publint 兼容默认值、语义化版本自动化和 changelog 生成。
8. 配置 package.json：设置 `"type": "module"`，`main` 指向 `dist/cjs/index.cjs`，`module` 指向 `dist/esm/index.js`，`types` 指向 `dist/esm/index.d.ts`；在 `exports` 中为 `.` 同时配置 `import` 和 `require` 的 `types` 与 `default`；`files` 包含 `dist` 和 `src`；`scripts` 包含 `build: vite build`、`lint: eslint .`、`test: vitest`。
9. 配置 tsconfig.json：设置 `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"]`。
10. 初始化 Changesets：运行 `npx changeset init`。
11. 创建 changeset：运行 `npx changeset`，在交互提示中选择包、bump 类型和摘要。
12. 配置 `.changeset/config.json`：设置 `changelog` 为 `@changesets/cli/changelog`，`commit: false`，`fixed: []`，`linked: []`，`access: "public"`，`baseBranch: "main"`，`updateInternalDependencies: "patch"`。
13. 配置 GitHub Actions CI：创建 `.github/workflows/ci.yml`，在 push 和 pull_request 到 main 时触发；步骤使用 `actions/checkout@v4`、`pnpm/action-setup@v2`、`actions/setup-node@v4`（`node-version: 20`、`cache: 'pnpm'`），然后运行 `pnpm install`、`pnpm build`、`pnpm lint`、`pnpm test`。
14. 配置 GitHub Actions 发布：创建 `.github/workflows/publish.yml`，在 push 到 main 时触发；使用相同 Node/pnpm 设置后运行 `pnpm install`、`pnpm build`；使用 `changesets/action@v1`，设置 `publish: pnpm publish -r`，并传入 `GITHUB_TOKEN` 和 `NPM_TOKEN` 环境变量。
15. 配置 pnpm monorepo 工作区：在 `pnpm-workspace.yaml` 中设置 `packages` 为 `['packages/*', 'examples/*']`。
16. 配置 Nx：在 `nx.json` 中设置 `tasksRunnerOptions.default.runner` 为 `nx/tasks-runners/default`，`options.cacheableOperations` 为 `["build", "lint", "test"]`，并设置 `targetDefaults.build.dependsOn` 为 `["^build"]`。
17. 配置 Prettier：在 `.prettierrc` 中设置 `semi: false`、`singleQuote: true`、`trailingComma: "all"`、`printWidth: 80`。
18. 配置 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`。
19. 使用 Vite 配置进行构建，以处理 ESM/CJS 双输出和声明文件。
20. 在 package.json 中使用 publint 兼容的 exports 以保证兼容性。
21. 在 monorepo 中使用 Changesets 进行版本管理。
22. 为 ESM-first 包在 package.json 中设置 `"type": "module"`。
23. 在 `files` 中同时包含 `src` 和 `dist`，以便 source map 调试。
24. 在 monorepo 中使用 Nx 缓存以加快构建。
25. 始终为 TypeScript 消费者生成声明文件（`.d.ts`）。
26. 使用 ESLint 配置作为跨包的一致基线。
27. 使用 GitHub Actions 和 Changesets 自动化发布。
28. 避免 package.json 缺少 `exports` 字段，否则会破坏现代打包器。
29. 避免未设置 `"type": "module"`，否则会导致 ESM 导入问题。
30. 避免构建输出中忘记声明文件。
31. 避免未从构建中排除测试文件。
32. 避免在未运行 publint 验证前发布。
33. 避免在 tsconfig 中未配置 `moduleResolution: "bundler"`。
34. 避免 monorepo 包之间版本不一致，使用 Changesets 的 `linked` 进行管理。

适用边界 · 注意事项

• 不适用于非 JavaScript/TypeScript 包开发。
• 不适用于不使用 Vite、pnpm、Changesets、GitHub Actions 或 Nx 的项目。
• 不适用于不需要双格式发布、monorepo 版本管理和自动化发布的简单项目。