tanstack-cli

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

References

• Configuration and Vite plugin setup
• Publishing and version management