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

Common Mistakes

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

Configuration

Installation

pnpm add -D @tanstack/vite-config vite publint

Basic Vite Configuration

The tanstackViteConfig function provides an opinionated Vite build setup for dual ESM/CJS publishing. Merge it with your own Vite config using mergeConfig:

import { defineConfig, mergeConfig } from 'vite';
import { tanstackViteConfig } from '@tanstack/vite-config';

const config = defineConfig({
  // Framework plugins, vitest config, etc.
});

export default mergeConfig(
  config,
  tanstackViteConfig({
    entry: './src/index.ts',
    srcDir: './src',
  }),
);

Configuration Options

The tanstackViteConfig function accepts an options object with these properties:

import { type Options } from '@tanstack/vite-config';

const options: Options = {
  // Required: entry file or array of entry files
  entry: './src/index.ts',
  // Or multiple entries:
  // entry: ['./src/index.ts', './src/utils.ts'],

  // Required: source directory for declaration file generation
  srcDir: './src',

  // Output directory (default: 'dist')
  outDir: './dist',

  // Generate CJS output alongside ESM (default: true)
  cjs: true,

  // Patterns to exclude from type generation
  exclude: ['./src/**/*.test.ts', './src/__mocks__'],

  // Path to custom tsconfig
  tsconfigPath: './tsconfig.build.json',

  // Additional dependencies to externalize (auto-detected from package.json)
  externalDeps: [/^@internal\//],

  // Dependencies to bundle instead of externalize
  bundledDeps: ['tiny-invariant'],

  // Hook to transform declaration file content before writing
  beforeWriteDeclarationFile: (filePath, content) => {
    return `// Generated by TanStack Config\n${content}`;
  },
};

Package.json Exports Configuration

The build output requires a properly configured exports field in package.json:

{
  "name": "my-library",
  "type": "module",
  "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"
      }
    },
    "./package.json": "./package.json"
  },
  "scripts": {
    "build": "vite build && publint --strict"
  }
}

Key requirements for package.json:

• "type": "module" must be set for ESM-first output
• The exports field defines both import (ESM) and require (CJS) conditions
• Each condition includes types first, then default for proper TypeScript resolution
• Export ./package.json for tools that need to read package metadata

Multiple Entry Points

For libraries with multiple entry points, use an array for the entry option and add corresponding exports:

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

{
  "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"
      }
    },
    "./utils": {
      "import": {
        "types": "./dist/esm/utils.d.ts",
        "default": "./dist/esm/utils.js"
      },
      "require": {
        "types": "./dist/cjs/utils.d.cts",
        "default": "./dist/cjs/utils.cjs"
      }
    },
    "./package.json": "./package.json"
  }
}

ESM-Only Output

To skip CJS generation, set cjs: false:

export default mergeConfig(
  config,
  tanstackViteConfig({
    entry: './src/index.ts',
    srcDir: './src',
    cjs: false,
  }),
);

When distributing ESM-only, simplify the exports field:

{
  "type": "module",
  "exports": {
    ".": {
      "types": "./dist/esm/index.d.ts",
      "default": "./dist/esm/index.js"
    },
    "./package.json": "./package.json"
  }
}

Dependency Handling

Dependencies listed in package.json (dependencies, peerDependencies) are automatically externalized. Use externalDeps to add patterns beyond what is auto-detected:

tanstackViteConfig({
  entry: './src/index.ts',
  srcDir: './src',
  externalDeps: [/^@internal\//, 'shared-utils'],
});

To force-bundle a dependency instead of externalizing it:

tanstackViteConfig({
  entry: './src/index.ts',
  srcDir: './src',
  bundledDeps: ['tiny-invariant', 'ts-invariant'],
});

Build Validation

Run publint --strict after the build to validate the package output:

pnpm build
# Runs: vite build && publint --strict

publint checks that the exports field matches actual build output, verifies file extensions are correct for ESM/CJS, and catches common packaging mistakes.

Publishing

Installation

pnpm add -D @tanstack/publish-config

Basic Publish Script

Create a publish script that uses the publish function from @tanstack/publish-config:

// scripts/publish.ts
import { publish } from '@tanstack/publish-config';

publish({
  branchConfigs: {
    main: {
      prerelease: false,
    },
    beta: {
      prerelease: true,
    },
    alpha: {
      prerelease: true,
    },
  },
  packages: [
    {
      name: '@tanstack/my-core',
      packageDir: 'packages/core',
    },
    {
      name: '@tanstack/my-react',
      packageDir: 'packages/react',
    },
  ],
  rootDir: process.cwd(),
  branch: process.env.BRANCH,
  tag: process.env.TAG,
  ghToken: process.env.GH_TOKEN,
})
  .then(() => {
    console.log('Successfully published packages!');
  })
  .catch((error) => {
    console.error('Publishing failed:', error);
    process.exit(1);
  });

The publish function is only available as an ESM import. Ensure your project has "type": "module" in package.json.

Publish Options

Branch Configurations

Branch configs control how each branch publishes to npm:

const branchConfigs = {
  // Stable releases, tagged as 'latest' on npm
  main: {
    prerelease: false,
  },

  // Beta prereleases, tagged as 'beta' on npm
  beta: {
    prerelease: true,
  },

  // Alpha prereleases, tagged as 'alpha' on npm
  alpha: {
    prerelease: true,
  },

  // Previous major version, tagged as 'previous' on npm
  v4: {
    prerelease: false,
    previousVersion: true,
  },
};

Each branch maps to an npm dist-tag:

• main with prerelease: false publishes as latest
• beta with prerelease: true publishes as beta
• alpha with prerelease: true publishes as alpha
• Branches with previousVersion: true publish as previous

Conventional Commit Versioning

The publish system determines version bumps from conventional commit messages:

Breaking changes indicated by BREAKING CHANGE in the commit body or feat!: prefix require a manual tag for major version bumps.

Manual Version Tags

For major version bumps or specific version overrides, pass a tag via environment variable:

TAG=v2.0.0 BRANCH=main npx tsx scripts/publish.ts

The tag must start with v followed by a valid semver version.

Monorepo Package Configuration

Define each publishable package with its name and directory:

const packages = [
  {
    name: '@tanstack/config',
    packageDir: 'packages/config',
  },
  {
    name: '@tanstack/vite-config',
    packageDir: 'packages/vite-config',
  },
  {
    name: '@tanstack/publish-config',
    packageDir: 'packages/publish-config',
  },
  {
    name: '@tanstack/eslint-config',
    packageDir: 'packages/eslint-config',
  },
];

GitHub Actions Integration

A typical CI workflow for publishing:

name: Publish
on:
  push:
    branches: [main, beta, alpha]

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v6
        with:
          node-version: 18
          registry-url: 'https://registry.npmjs.org'
      - run: pnpm install
      - run: pnpm build
      - run: npx tsx scripts/publish.ts
        env:
          BRANCH: ${{ github.ref_name }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Requirements

The following tools must be available in the publishing environment:

• Node.js v18.17+
• pnpm v8+ (only supported package manager)
• Git CLI (for commit history analysis)
• GitHub CLI (pre-installed on GitHub Actions)