TanStack Config

Overview

TanStack Config provides opinionated tooling to build, version, and publish JavaScript/TypeScript packages with minimal configuration and consistent results. It uses Vite for library builds with automatic dual ESM/CJS output and type generation, plus automated publishing with conventional-commit-based versioning.

When to use: Building TanStack libraries or packages that follow TanStack conventions, contributing to TanStack open-source projects, setting up dual ESM/CJS library builds with Vite, automating package publishing with conventional commits.

When NOT to use: Application builds (use framework-specific tooling), non-library projects, projects not using pnpm, projects that need non-Vite build pipelines.

Quick Reference

Pattern	API / Package	Key Points
Vite build config	`tanstackViteConfig()` from `@tanstack/vite-config`	Merge with `defineConfig` via `mergeConfig`
Entry point	`entry: './src/index.ts'`	Single file or array of entry files
Source directory	`srcDir: './src'`	Used for declaration file generation
CJS output	`cjs: true` (default)	Generates `.cjs` and `.d.cts` alongside ESM
External deps	`externalDeps: [/^@internal\//]`	Auto-detected from `package.json`, extend with patterns
Bundled deps	`bundledDeps: ['tiny-invariant']`	Bundle instead of externalize
Exclude from types	`exclude: ['./src/*/.test.ts']`	Patterns to skip during type generation
Custom tsconfig	`tsconfigPath: './tsconfig.build.json'`	Override default tsconfig for builds
Declaration hook	`beforeWriteDeclarationFile(path, content)`	Transform `.d.ts` content before write
Publish automation	`publish()` from `@tanstack/publish-config`	Conventional commits drive versioning
Branch configs	`branchConfigs: { main, beta, alpha }`	Control prerelease and stable channels
Package list	`packages: [{ name, packageDir }]`	Monorepo package definitions
Build script	`vite build && publint --strict`	Standard build with strict linting

Common Mistakes

Mistake	Correct Pattern
Missing `"type": "module"` in `package.json`	Set `"type": "module"` for ESM-first builds
Using `defineConfig` alone without `mergeConfig`	Use `mergeConfig(defineConfig({...}), tanstackViteConfig({...}))`
Forgetting `entry` or `srcDir` options	Both are required for `tanstackViteConfig` to work
Missing `exports` field in `package.json`	Define `import` and `require` conditions with types
Not awaiting `publish()` promise	Handle with `.then()` and `.catch()` for error reporting
Using npm or yarn instead of pnpm	pnpm is the only supported package manager
Omitting `publint --strict` from build script	Add `publint --strict` after `vite build` to catch packaging issues
Setting `tag` without `v` prefix	Manual version tags must start with `v` (e.g., `v1.0.0`)
Wrong commit type for release level	`fix`/`refactor`/`perf` = patch, `feat` = minor, `BREAKING CHANGE` = major

Requirements

Node.js v18.17+
pnpm v8+
Git CLI
GitHub CLI (pre-installed on GitHub Actions)
Vite (peer dependency for build config)
publint (recommended for build validation)

Delegation

Build configuration review: Use Task agent to verify Vite config and package.json exports
Publishing workflow setup: Use Explore agent to check CI/CD integration patterns
Package validation: Run publint --strict after builds to catch packaging issues