tsup

Bundle your TypeScript library with no config, powered by esbuild

weekly downloads3.5M

versionv8.5.1

licenseMIT

categorybuild-tool

Overview

tsup is a TypeScript bundler built on top of esbuild that requires minimal to no configuration to package your TypeScript libraries for npm distribution. It handles the entire build pipeline—TypeScript compilation, bundling, minification, and type declaration generation—without the complexity typically associated with tools like webpack or Rollup. With over 3.5 million weekly downloads, it has become a go-to solution for library authors who want to focus on writing code rather than maintaining build configurations.

The primary value proposition of tsup is its ability to generate multiple output formats simultaneously. Modern JavaScript libraries need to support both ESM (for modern bundlers and Node.js) and CommonJS (for legacy Node.js environments), along with TypeScript declaration files for type checking. tsup handles all of this automatically with a single command, detecting your entry points and producing optimized bundles with source maps and tree-shaking enabled by default.

tsup is specifically designed for library authors, not application developers. While tools like Vite or Next.js handle application bundling, tsup focuses on creating distributable packages that other developers will import. It leverages esbuild's speed (written in Go) to provide near-instantaneous builds, even for large codebases. The tool supports watch mode for development, code splitting for advanced use cases, and custom configurations when you need more control, but its zero-config defaults work for the majority of TypeScript libraries.

Developers building React component libraries, utility packages, CLI tools, or any TypeScript code intended for npm distribution are the primary users. The tool has become particularly popular in the modern TypeScript ecosystem because it eliminates the need to understand complex bundler configurations while still producing professional-grade outputs that meet npm publishing standards.

Quick Start

typescript

// src/index.ts - Your library code
export function formatBytes(bytes: number, decimals: number = 2): string {
  if (bytes === 0) return '0 Bytes';
  const k = 1024;
  const sizes = ['Bytes', 'KB', 'MB', 'GB'];
  const i = Math.floor(Math.log(bytes) / Math.log(k));
  return parseFloat((bytes / Math.pow(k, i)).toFixed(decimals)) + ' ' + sizes[i];
}

export class DataProcessor {
  constructor(private data: string[]) {}
  
  process(): number {
    return this.data.filter(d => d.length > 0).length;
  }
}

// package.json - Configure output locations
{
  "name": "my-library",
  "version": "1.0.0",
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.cjs",
      "types": "./dist/index.d.ts"
    }
  },
  "scripts": {
    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
    "dev": "tsup src/index.ts --format esm,cjs --dts --watch"
  },
  "devDependencies": {
    "tsup": "^8.5.1",
    "typescript": "^5.0.0"
  }
}

// tsup.config.ts - Optional advanced configuration
import { defineConfig } from 'tsup';

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
  splitting: false,
  sourcemap: true,
  clean: true,
  minify: process.env.NODE_ENV === 'production'
});

Use Cases

Publishing a TypeScript utility library: You've written a collection of helper functions in TypeScript and want to publish them to npm. tsup generates both ESM and CommonJS versions along with type declarations, ensuring compatibility with all consumer environments without requiring them to have TypeScript installed.

Building React component libraries: When creating a reusable component library, tsup bundles your React components with their dependencies tree-shaken, generates proper type definitions, and outputs multiple formats. This allows consumers to import your components with full TypeScript support and minimal bundle size impact.

Creating Node.js CLI tools: For command-line applications written in TypeScript, tsup bundles everything into a single executable file with proper shebang support, including all dependencies. This simplifies distribution and ensures users don't need to install transitive dependencies.

Rapid prototyping and development: The watch mode with fast rebuilds makes tsup ideal for library development workflows. Changes are rebundled in milliseconds, allowing you to test your package locally using npm link or package managers' workspace features without slow rebuild cycles.

Monorepo package building: In monorepos with multiple internal packages, tsup provides consistent build outputs across all packages with minimal configuration duplication. Each package can have its own tsup config or rely on shared defaults, making it easier to maintain build consistency across dozens of packages.

Pros & Cons

Pros

+Extremely fast builds thanks to esbuild, typically 10-100x faster than webpack or Rollup
+Zero configuration required for standard use cases—just point it at your entry file
+Automatically generates both ESM and CJS outputs with type declarations in a single command
+Built-in tree-shaking and minification reduce bundle sizes without additional plugins
+Simple CLI and programmatic API that's easy to integrate into existing workflows

Cons

−Less flexible than Rollup or webpack for complex, non-standard build requirements
−esbuild limitations carry over—limited support for some advanced TypeScript features like emitDecoratorMetadata
−Smaller plugin ecosystem compared to mature bundlers, making custom transformations harder
−Not designed for application bundling—lacks features like HTML generation or dev servers
−Type declaration generation can be slow for large projects since it uses the TypeScript compiler, not esbuild

Alternatives

esbuildv0.27.3

An extremely fast JavaScript and CSS bundler and minifier.

build-tool

105.3M / week

rollupv4.57.1

Next-generation ES module bundler

build-toolmodulesbundler

67.9M / week

unbuildv3.6.1

A unified JavaScript build system

build-tool

196K / week

vitev7.3.1

Native-ESM powered web dev build tool

build-toolfrontendframework

53.5M / week

Comparisons

tsup vs rollup

build-tool

Install

bash

npm install tsup

bash

pnpm add tsup

bash

bun add tsup

Overview

Quick Start

typescript

// src/index.ts - Your library code
export function formatBytes(bytes: number, decimals: number = 2): string {
  if (bytes === 0) return '0 Bytes';
  const k = 1024;
  const sizes = ['Bytes', 'KB', 'MB', 'GB'];
  const i = Math.floor(Math.log(bytes) / Math.log(k));
  return parseFloat((bytes / Math.pow(k, i)).toFixed(decimals)) + ' ' + sizes[i];
}

export class DataProcessor {
  constructor(private data: string[]) {}
  
  process(): number {
    return this.data.filter(d => d.length > 0).length;
  }
}

// package.json - Configure output locations
{
  "name": "my-library",
  "version": "1.0.0",
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.cjs",
      "types": "./dist/index.d.ts"
    }
  },
  "scripts": {
    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
    "dev": "tsup src/index.ts --format esm,cjs --dts --watch"
  },
  "devDependencies": {
    "tsup": "^8.5.1",
    "typescript": "^5.0.0"
  }
}

// tsup.config.ts - Optional advanced configuration
import { defineConfig } from 'tsup';

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  dts: true,
  splitting: false,
  sourcemap: true,
  clean: true,
  minify: process.env.NODE_ENV === 'production'
});

Use Cases

Pros & Cons

Pros

+Extremely fast builds thanks to esbuild, typically 10-100x faster than webpack or Rollup
+Zero configuration required for standard use cases—just point it at your entry file
+Automatically generates both ESM and CJS outputs with type declarations in a single command
+Built-in tree-shaking and minification reduce bundle sizes without additional plugins
+Simple CLI and programmatic API that's easy to integrate into existing workflows

Cons

−Less flexible than Rollup or webpack for complex, non-standard build requirements
−esbuild limitations carry over—limited support for some advanced TypeScript features like emitDecoratorMetadata
−Smaller plugin ecosystem compared to mature bundlers, making custom transformations harder
−Not designed for application bundling—lacks features like HTML generation or dev servers
−Type declaration generation can be slow for large projects since it uses the TypeScript compiler, not esbuild