Imported from terminalskills/skills (skills/tsup/SKILL.md). Install upstream with npx skills add terminalskills/skills --skill tsup. Copyright stays with the author (Apache-2.0).

tsup

Overview

tsup bundles TypeScript libraries for npm publishing — zero config, powered by esbuild (100x faster than tsc). Outputs ESM + CJS dual packages, generates .d.ts declaration files, and handles tree-shaking. The standard tool for building TypeScript packages in 2025+.

When to Use

• Publishing a TypeScript library to npm
• Need both ESM and CJS output (dual package)
• Building internal packages in a monorepo
• Want fast builds without configuring Rollup/Webpack
• Generating .d.ts files alongside bundled output

Instructions

Setup

npm install -D tsup typescript

Zero Config

// package.json — Minimal setup
{
  "name": "my-lib",
  "version": "1.0.0",
  "type": "module",
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
      "require": { "types": "./dist/index.d.cts", "default": "./dist/index.cjs" }
    }
  },
  "files": ["dist"],
  "scripts": {
    "build": "tsup",
    "dev": "tsup --watch"
  }
}

// tsup.config.ts — Build configuration
import { defineConfig } from "tsup";

export default defineConfig({
  entry: ["src/index.ts"],
  format: ["esm", "cjs"],       // Dual ESM + CJS output
  dts: true,                     // Generate .d.ts files
  splitting: true,               // Code splitting for ESM
  clean: true,                   // Clean dist/ before build
  treeshake: true,               // Remove unused code
  sourcemap: true,
  minify: false,                 // Don't minify libraries
  outDir: "dist",
});

Multiple Entry Points

// tsup.config.ts — Library with subpath exports
import { defineConfig } from "tsup";

export default defineConfig({
  entry: {
    index: "src/index.ts",
    client: "src/client.ts",
    server: "src/server.ts",
    utils: "src/utils/index.ts",
  },
  format: ["esm", "cjs"],
  dts: true,
  clean: true,
});

// package.json — Subpath exports
{
  "exports": {
    ".": { "import": "./dist/index.js", "require": "./dist/index.cjs" },
    "./client": { "import": "./dist/client.js", "require": "./dist/client.cjs" },
    "./server": { "import": "./dist/server.js", "require": "./dist/server.cjs" },
    "./utils": { "import": "./dist/utils.js", "require": "./dist/utils.cjs" }
  }
}

Environment-Specific Builds

// tsup.config.ts — Different builds for browser and Node
import { defineConfig } from "tsup";

export default defineConfig([
  {
    entry: ["src/index.ts"],
    format: ["esm"],
    platform: "browser",          // Browser-optimized
    globalName: "MyLib",
    outDir: "dist/browser",
  },
  {
    entry: ["src/index.ts"],
    format: ["esm", "cjs"],
    platform: "node",             // Node.js optimized
    target: "node18",
    outDir: "dist/node",
    dts: true,
  },
]);

Examples

Example 1: Publish a TypeScript utility library

User prompt: "I have a collection of TypeScript utility functions. Package them for npm with ESM and CJS support."

The agent will configure tsup for dual output, set up package.json exports, generate type declarations, and prepare for npm publish.

Example 2: Build a React component library

User prompt: "Bundle my React component library with TypeScript types and tree-shaking."

The agent will set up tsup with React external, multiple entry points per component, CSS handling, and declaration file generation.

Guidelines

• format: ["esm", "cjs"] — always ship both for maximum compatibility
• dts: true — generate TypeScript declarations (uses a separate process)
• clean: true — prevent stale files in dist/
• Don't minify libraries — let the consumer's bundler handle it
• external for peer deps — don't bundle React, Vue, etc.
• splitting for ESM — enables tree-shaking for consumers
• exports in package.json — modern Node.js resolution, types condition first
• files: ["dist"] — only publish the built output
• treeshake: true — remove internal unused code from output
• Watch mode — tsup --watch for development