ts-builds

Shared TypeScript build tooling. Bundles ESLint, Prettier, Vitest, TypeScript and provides a CLI for running standardized commands across projects.

Quick Start

New Project

mkdir my-library && cd my-library
pnpm init

# Install (bundles all tooling)
pnpm add -D ts-builds tsdown

# Initialize
npx ts-builds init      # Creates .npmrc with hoist patterns
npx ts-builds config    # Creates ts-builds.config.json

# Create source files
mkdir src test
echo 'export const hello = () => "Hello!"' > src/index.ts

# Validate
npx ts-builds validate

Existing Project

pnpm add -D ts-builds tsdown

npx ts-builds init      # Creates .npmrc
npx ts-builds config    # Creates config file
npx ts-builds cleanup   # Remove redundant dependencies

npx ts-builds validate

CLI Commands

Setup Commands

npx ts-builds init           # Create .npmrc with hoist patterns
npx ts-builds config         # Create ts-builds.config.json
npx ts-builds config --force # Overwrite existing config
npx ts-builds info           # Show bundled packages
npx ts-builds cleanup        # Remove redundant dependencies
npx ts-builds help           # Show all commands

Script Commands

npx ts-builds validate       # Run full validation chain
npx ts-builds format         # Format with Prettier
npx ts-builds format:check   # Check formatting only
npx ts-builds lint           # Lint with ESLint (--fix)
npx ts-builds lint:check     # Check lint only
npx ts-builds typecheck      # TypeScript type checking
npx ts-builds test           # Run tests once
npx ts-builds test:watch     # Watch mode
npx ts-builds test:coverage  # With coverage
npx ts-builds build          # Production build (tsdown or vite)
npx ts-builds dev            # Dev mode (tsdown --watch or vite dev server)
npx ts-builds preview        # Preview production build (vite preview)

Analysis Commands

npx ts-builds size               # Report bundle sizes (raw + gzip)
npx ts-builds size --save        # Save baseline for delta tracking
npx ts-builds doctor             # Check package health (exports, files, types)
npx ts-builds changelog          # Generate changelog from conventional commits
npx ts-builds changelog --since v1.0.0 --version 2.0.0  # From specific tag
npx ts-builds changelog --output CHANGELOG.md            # Write to file

Package.json Scripts

Add these to delegate all commands to ts-builds:

{
  "scripts": {
    "validate": "ts-builds validate",
    "format": "ts-builds format",
    "format:check": "ts-builds format:check",
    "lint": "ts-builds lint",
    "lint:check": "ts-builds lint:check",
    "typecheck": "ts-builds typecheck",
    "test": "ts-builds test",
    "test:watch": "ts-builds test:watch",
    "build": "ts-builds build",
    "dev": "ts-builds dev",
    "prepublishOnly": "pnpm validate"
  }
}

Configuration

Create ts-builds.config.json to customize behavior:

Basic

{
  "srcDir": "./src",
  "validateChain": ["format", "lint", "typecheck", "test", "build"]
}

With Custom ESLint Plugins

If your project uses ESLint plugins not bundled with ts-builds (e.g., eslint-plugin-react-hooks):

{
  "srcDir": "./src",
  "lint": {
    "useProjectEslint": true
  }
}

This tells ts-builds to use your project's ESLint installation instead of the bundled version.

For SPAs/React Apps (Vite)

Use Vite instead of tsdown for SPA builds:

pnpm add -D ts-builds vite

{
  "srcDir": "./src",
  "buildMode": "vite"
}

With buildMode: "vite":

• ts-builds build → vite build
• ts-builds dev → vite (dev server with HMR)
• ts-builds preview → vite preview

Bundle Size Thresholds

{
  "size": {
    "maxTotal": 51200,
    "maxFile": 20480,
    "gzip": true,
    "baselineFile": ".ts-builds-size.json"
  }
}

Changelog

{
  "changelog": {
    "types": { "feat": "Features", "fix": "Bug Fixes" },
    "exclude": ["chore", "ci"]
  }
}

Advanced (Monorepos, Custom Commands)

{
  "srcDir": "./src",
  "commands": {
    "compile": "tsc",
    "docs:validate": "pnpm docs:build && pnpm docs:check",
    "landing:validate": { "run": "pnpm validate", "cwd": "./landing" }
  },
  "chains": {
    "validate": ["validate:core", "validate:landing"],
    "validate:core": ["format", "lint", "compile", "test", "docs:validate", "build"],
    "validate:landing": ["landing:validate"]
  }
}

Run named chains:

npx ts-builds validate:core
npx ts-builds validate:landing

Extendable Configs

ts-builds exports base configurations you can extend:

ESLint

// eslint.config.js
import baseConfig from "ts-builds/eslint"

export default [...baseConfig]

Vitest

// vitest.config.ts
import { defineConfig } from "vitest/config"
import baseConfig from "ts-builds/vitest"

export default defineConfig(baseConfig)

TypeScript

{
  "extends": "ts-builds/tsconfig",
  "compilerOptions": {
    "outDir": "./dist"
  }
}

tsdown

// tsdown.config.ts
import baseConfig from "ts-builds/tsdown"

export default baseConfig

Prettier

{
  "prettier": "ts-builds/prettier"
}

Vite (for SPAs)

// vite.config.ts
import { vite } from "ts-builds/vite"
import { defineConfig, mergeConfig } from "vite"

export default defineConfig(
  mergeConfig(vite, {
    // your customizations
  }),
)

Bundled Packages

Run npx ts-builds info to see all bundled packages. You don't need to install:

• eslint, prettier, typescript, typescript-eslint, vitest
• @eslint/js, eslint-plugin-prettier, eslint-plugin-simple-import-sort
• eslint-config-prettier (flagged by cleanup)
• @vitest/coverage-v8, @vitest/ui
• cross-env, rimraf, ts-node

License

MIT